GS2-Schedule

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 --> Absolute["Absolute period<br/>(scheduleType = absolute)"]
  Event --> Relative["Relative period<br/>(scheduleType = relative)"]
  Absolute --> AbsoluteSample["e.g. New Year event<br/>from Jan 1 to Jan 3"]
  Relative --> RelativeSample["e.g. 7 days from first play,<br/>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.

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.

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.

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

    const auto Domain = Gs2->Schedule->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    );
    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());
    }

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.

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

    const auto Domain = Gs2->Schedule->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Event(
        "event-0001" // eventName
    );
    const auto Item = Domain->Model();

Obtaining a list of triggers

You can obtain a list of relative-period triggers pulled for the player, along with their expiration dates.

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

    const auto Domain = Gs2->Schedule->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    );
    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());
    }

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.

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

    const auto Domain = Gs2->Schedule->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Event(
        "event-0001" // eventName
    )->RepeatSchedule(
    );
    const auto Item = Domain->Model();

Detailed Reference