GS2-Schedule SDK for Game Engine API Reference

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

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.

Type Condition 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
*
 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.
Related methods:
getTrigger - Get a specific trigger's status
listTriggers - Get a list of the player's active triggers

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).
DefinitionDescription
“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”
Related methods:
getEvent - Get a specific event's schedule status
listEvents - Get a list of currently active events for the player

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 Condition Required Default 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.
Related methods:
getEvent - Get a specific event's schedule status

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 Condition Required Default 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);

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);

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 Condition Required Default 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);

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);