GS2-Schedule SDK for Game Engine API Reference

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

Model

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.

	Type	Required	Default	Value Limits	Description
triggerId	string	*		~ 1024 chars	Trigger 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	*	Now		Datetime of creation 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.

Type Condition Required Default Value Limits Description

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.

	Type	Required	Value Limits	Description
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

	Type	Required	Value Limits	Description
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

    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Trigger(
        triggerName: "trigger1"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Trigger(
        triggerName: "trigger1"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Schedule->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Trigger(
        "trigger1" // triggerName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

Value change event handling

    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Trigger(
        triggerName: "trigger1"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);

    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Trigger(
        triggerName: "trigger1"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);

    const auto Domain = Gs2->Schedule->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Trigger(
        "trigger1" // triggerName
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Schedule::Model::FTrigger> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

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

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

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

Result

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

Implementation Example

    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.TriggersAsync(
    ).ToListAsync();

    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Triggers(
    );
    List<EzTrigger> items = new List<EzTrigger>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

    const auto Domain = Gs2->Schedule->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->Triggers(
    );
    TArray<Gs2::UE5::Schedule::Model::FEzTriggerPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

Value change event handling

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

    // Stop event handling
    domain.UnsubscribeTriggers(callbackId);

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

    // Stop event handling
    domain.UnsubscribeTriggers(callbackId);

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

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

Warning

This event is triggered when the value stored in the SDK’s local cache changes.

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

	Type	Required	Value Limits	Description
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

    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Event(
        eventName: "event-0001"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Event(
        eventName: "event-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Schedule->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Event(
        "event-0001" // eventName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

Value change event handling

    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Event(
        eventName: "event-0001"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);

    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Event(
        eventName: "event-0001"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);

    const auto Domain = Gs2->Schedule->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Event(
        "event-0001" // eventName
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Schedule::Model::FEvent> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

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

Warning

This event is triggered when the value stored in the SDK’s local cache changes.

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

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

Result

	Type	Description
items	List<EzEvent>	List of Events

Implementation Example

    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.EventsAsync(
    ).ToListAsync();

    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Events(
    );
    List<EzEvent> items = new List<EzEvent>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

    const auto Domain = Gs2->Schedule->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->Events(
    );
    TArray<Gs2::UE5::Schedule::Model::FEzEventPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

Value change event handling

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

    // Stop event handling
    domain.UnsubscribeEvents(callbackId);

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

    // Stop event handling
    domain.UnsubscribeEvents(callbackId);

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

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

Warning

This event is triggered when the value stored in the SDK’s local cache changes.

Therefore, callbacks will not be invoked if the value is changed in any other way.