API Reference of GS2-Schedule SDK for Game Engine

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

Model

EzTrigger

Trigger

A trigger is an entity that defines the starting point for the beginning of an event when realizing different event durations for different game players.

	Type	Required	Default	Value Limits	Description
triggerId	string	✓		~ 1024 chars	Trigger GRN
name	string	✓		~ 128 chars	Trigger Name
createdAt	long	✓	Now		Datetime of creation Unix time, milliseconds Automatically configured on the server
expiresAt	long	✓			Trigger Expiration Date

EzEvent

Event

Two types of event durations exist: absolute and relative. Absolute periods are fixed periods, such as January 1, 2021 00:00(UTC) to January 7, 2021 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 pulled.

The event can be set to repeat itself as well as the duration of the event. 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 Type Name

metadata string ~ 2048 chars Metadata

scheduleType

String Enum
enum {
“absolute”,
“relative”
}

✓

~ 128 chars

Type of Event Period

Enumerator String Definition	Description
“absolute”	Fixed period
“relative”	Period by Player

absoluteBegin long Event start date and time

absoluteEnd long Event end date and time

relativeTriggerName

string

{scheduleType} == “relative”

✓*

~ 128 chars

Event Start Trigger Name

When setting an event period for each game player, specify the name of the trigger that serves as the starting point for the event under relative.

* required if scheduleType is “relative”

EzRepeatSchedule

State of repeating schedule

	Type	Required	Value Limits	Description
repeatCount	int	✓	0 ~ 2147483646	Number of times to repeat
currentRepeatStartAt	long			Start date and time of repeating event
currentRepeatEndAt	long			End date and time of repeating event
lastRepeatEndAt	long			End date and time of last event
nextRepeatStartAt	long			Start date and time of next event

Methods

getTrigger

Get the trigger being pulled

Request

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name
triggerName	string	✓	~ 128 chars	Trigger Name
accessToken	string	✓	~ 128 chars	Access token

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"
    );
    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
    );
    
    // 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 called when the value in the local cache that the SDK has is changed.

The local cache will only be changed by executing the SDK’s API, or by executing a stamp sheet via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. GS2-Gateway notification enabled.

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

listTriggers

Get list of triggers being pulled

Request

	Type	Condition	Required	Default	Value Limits	Description
namespaceName	string		✓		~ 128 chars	Namespace name
accessToken	string		✓		~ 128 chars	Access token

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
    );
    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
    );
    
    // 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 called when the value in the local cache that the SDK has is changed.

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

getEvent

Retrieve ongoing events

Request

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name
eventName	string	✓	~ 128 chars	Event Type Name
accessToken	string	✓	~ 128 chars	Access token

Result

	Type	Description
item	EzEvent	Event
inSchedule	bool	Whether in schedule
scheduleStartAt	long	Schedule start time
scheduleEndAt	long	Schedule end time
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"
    );
    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
    );
    
    // 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 called when the value in the local cache that the SDK has is changed.

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

listEvents

Get list of events currently being held

Request

	Type	Condition	Required	Default	Value Limits	Description
namespaceName	string		✓		~ 128 chars	Namespace name
accessToken	string		✓		~ 128 chars	Access token

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
    );
    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
    );
    
    // 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 called when the value in the local cache that the SDK has is changed.

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