> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-Schedule SDK for Game Engine API 레퍼런스

게임 엔진용 GS2-Schedule SDK의 모델 사양과 API 레퍼런스



## 모델

### EzTrigger

트리거<br>

상대 이벤트 스케줄링의 기점을 정의하여 플레이어별 이벤트 기간을 구현합니다.<br>
플레이어에게 트리거가 발동되면 유효 기간(expiresAt)이 설정됩니다.<br>
"relative" 스케줄 타입으로 설정된 이벤트는 트리거를 이름으로 참조하며, 해당 플레이어의 이벤트 기간은 트리거가 발동된 시각부터 유효 기간까지 지속됩니다.<br>
트리거는 갱신할 수 있으며, 유효 기간이 지나면 TTL에 의해 자동으로 정리됩니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| triggerId | string |  | ※ |  |  ~ 1024자 | 트리거 GRN<br>※ 서버가 자동으로 설정 |
| name | string |  | ✓ |  |  ~ 128자 | 트리거 이름<br>트리거 고유 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| triggeredAt | long |  | ※ | 현재 시각 |  | 트리거 발동 일시<br>이 트리거가 발동된 타임스탬프입니다.<br>상대 이벤트 스케줄링의 기준 시작점 역할을 합니다. 명시적으로 지정하지 않으면 현재 시각이 자동으로 설정됩니다.<br>UNIX 시간(밀리초)으로 표현됩니다. |
| expiresAt | long |  | ✓ |  |  | 유효 기간<br>이 트리거가 만료되어 상대 이벤트 기간이 종료되는 타임스탬프입니다.<br>이 시각 이후 트리거는 만료된 것으로 간주되며(IsExpire가 true를 반환), 해당 플레이어에 대한 관련 상대 이벤트는 더 이상 유효하지 않습니다.<br>트리거 데이터는 만료 후 DynamoDB TTL에 의해 자동으로 정리됩니다. UNIX 시간(밀리초)으로 표현됩니다. |

**관련 메서드:**
getTrigger - 특정 트리거의 상태 조회
listTriggers - 플레이어의 유효한 트리거 목록 조회


---

### EzEvent

이벤트<br>

이벤트의 기간에는 절대 기간과 상대 기간의 2가지 종류가 있습니다.<br>
절대 기간은 예를 들어 YYYY년 MM월 DD일 00:00(UTC) ~ YYYY년 MM월 DD일 23:59(UTC)와 같은 고정된 기간이며,<br>
상대 기간은 트리거를 당긴 시점부터 24시간과 같이 게임 플레이어마다 다른 기간을 이벤트 기간으로 하는 것입니다.<br>

이벤트에는 개최 기간뿐만 아니라 반복도 설정할 수 있게 되어 있어<br>
이벤트 기간 중 월요일 10:00 ~ 11:00만을 이벤트 기간으로 하는 설정도 가능합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128자 | 이벤트 이름<br>이벤트 고유의 이름. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 2048자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| scheduleType | 문자열 열거형<br>enum {<br>"absolute",<br>"relative"<br>}<br> |  | ✓ |  |  | 스케줄 타입<br>이벤트 기간을 정의하는 방식을 결정합니다.<br>"absolute"는 모든 플레이어에게 동일하게 적용되는 고정된 시작/종료 타임스탬프를 사용합니다.<br>"relative"는 플레이어별 트리거를 기점으로 사용하여, 개인화된 이벤트 기간을 구현합니다(예: 각 플레이어가 처음 로그인한 시점부터 24시간).absolute: 고정 기간 / relative: 플레이어별 기간 /  |
| absoluteBegin | long |  |  |  |  | 절대 시작 일시<br>절대 스케줄링에서 이벤트 기간의 고정 시작 시각입니다.<br>모든 플레이어가 동일한 시작 시각을 공유합니다. 절대 이벤트에서 설정하지 않으면 이벤트는 과거부터 시작된 것으로 취급됩니다.<br>UNIX 시간(밀리초)으로 표현됩니다. |
| absoluteEnd | long |  |  |  |  | 절대 종료 일시<br>절대 스케줄링에서 이벤트 기간의 고정 종료 시각입니다.<br>모든 플레이어가 동일한 종료 시각을 공유합니다. 절대 이벤트에서 설정하지 않으면 이벤트는 종료되지 않는 것으로 취급됩니다.<br>UNIX 시간(밀리초)으로 표현됩니다. |
| relativeTriggerName | string | {scheduleType} == "relative" | ✓※ |  |  ~ 128자 | 이벤트 시작 트리거 이름<br>게임 플레이어별로 이벤트 기간을 설정하는(`relative`) 경우, 이벤트 시작의 기점이 되는 트리거의 이름을 지정합니다.<br>영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.<br><br>※ scheduleType이(가) "relative" 이면 필수 |

**관련 메서드:**
getEvent - 특정 이벤트의 스케줄 상태 조회
listEvents - 플레이어의 현재 개최 중인 이벤트 목록 조회


---

### EzRepeatSchedule

반복 스케줄 상태<br>

특정 시점에서의 이벤트 반복 사이클의 현재 상태를 나타냅니다.<br>
반복 횟수(사이클이 발생한 횟수), 현재 활성 윈도우의 시작·종료 시각,<br>
전회 완료된 윈도우의 종료 시각, 그리고 다음 윈도우의 시작 시각을 포함합니다.<br>
이 정보는 이벤트의 반복 설정과 현재 시각을 토대로 동적으로 계산됩니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| repeatCount | int |  | ✓ |  | 0 ~ 2147483646 | 반복 횟수<br>현재 시각까지 완료된 반복 사이클의 횟수.<br>반복 윈도우가 종료될 때마다 증가합니다. 시즌제나 정기 이벤트의 사이클 진행 상황을 추적하는 데 사용할 수 있습니다. |
| currentRepeatStartAt | long |  |  |  |  | 현재 반복 시작 일시<br>현재 활성 상태인 반복 윈도우의 시작 시각.<br>이벤트가 현재 활성 상태인 반복 윈도우에 있지 않은 경우 null 입니다. UNIX 시간(밀리초)으로 표현됩니다. |
| currentRepeatEndAt | long |  |  |  |  | 현재 반복 종료 일시<br>현재 활성 상태인 반복 윈도우의 종료 시각.<br>이벤트가 현재 활성 상태인 반복 윈도우에 있지 않은 경우 null 입니다. UNIX 시간(밀리초)으로 표현됩니다. |
| lastRepeatEndAt | long |  |  |  |  | 직전 반복 종료 일시<br>가장 최근에 완료된 반복 윈도우의 종료 시각.<br>아직 반복 윈도우가 종료되지 않은 경우 null 입니다. UNIX 시간(밀리초)으로 표현됩니다. |
| nextRepeatStartAt | long |  |  |  |  | 다음 반복 시작 일시<br>다음 반복 윈도우의 시작 시각.<br>이벤트 기간 내에 다음 반복 윈도우가 없는 경우 null 입니다. UNIX 시간(밀리초)으로 표현됩니다. |

**관련 메서드:**
getEvent - 특정 이벤트의 스케줄 상태 조회


---

## 메서드

### getTrigger

특정 트리거의 상태 조회<br>

이름을 지정하여 특정 트리거를 조회하고, 언제 활성화되었는지, 언제 만료되는지를 확인할 수 있습니다.<br>
특정 트리거의 상태를 확인하는 데 사용합니다. 예를 들어 "first_login" 트리거가 아직 유효한지, 만료까지 남은 시간은 얼마인지 확인하여 "초보자 보너스 종료까지 남은 3일 12시간"과 같이 관련 이벤트의 카운트다운을 표시하는 경우에 유용합니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| triggerName | string |  | ✓|  |  ~ 128자 | 트리거 이름<br>트리거 고유 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzTrigger](#eztrigger) | 트리거|

#### 구현 예제




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

```

**Unity (Vanilla)**
```cs
    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;

```

**Unreal Engine 5**
```cpp
    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;
    }

```

**Godot**
```gdscript

var domain = ez.schedule.namespace_(
        "namespace-0001"
    ).me(game_session).trigger(
        "trigger1"
    )

var async_result = await domain.model()
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

```


##### 값 변경 이벤트 핸들링




**Unity (UniTask)**
```csharp
    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Trigger(
        triggerName: "trigger1"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Trigger(
        triggerName: "trigger1"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Schedule->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Trigger(
        "trigger1" // triggerName
    );
    
    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Schedule::Model::FTrigger> value) {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    Domain->Unsubscribe(CallbackId);

```

**Godot**
```gdscript

var domain = ez.schedule.namespace_(
        "namespace-0001"
    ).me(game_session).trigger(
        "trigger1"
    )

# 이벤트 핸들링 시작
var callback_id = domain.subscribe_model(func(value):
    # 값이 변화했을 때 호출됨
    # value에는 변경 후의 값이 전달됩니다
    pass
)

# 이벤트 핸들링 정지
domain.unsubscribe_model(callback_id)

```


**⚠️ Warning**

이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.

로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.

따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.

---

### listTriggers

플레이어의 유효한 트리거 목록 조회<br>

플레이어에 대해 현재 유효한 모든 트리거를 조회합니다.<br>
트리거는 상대 스케줄 이벤트를 활성화하기 위한 플레이어별 타이머입니다. 트리거가 "당겨지면"(활성화되면) 카운트다운이 시작되고, 해당 트리거에 연결된 이벤트가 플레이어에 대해 활성화됩니다.<br>
예를 들어 "first_login" 트리거가 "7일간 초보자 보너스" 이벤트를 활성화하거나, "first_purchase" 트리거가 "24시간 감사 세일" 이벤트를 활성화할 수 있습니다.<br>
각 트리거에는 유효 기간이 있으며, 기간이 만료되면 해당 플레이어에 대한 관련 이벤트도 종료됩니다.<br>
플레이어에게 현재 어떤 트리거가 유효한지 확인하는 데 사용합니다. 예를 들어 상태 화면에서 "초보자 보너스: 유효(남은 5일 후 만료)"와 같이 표시하는 경우에 유용합니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| items | [List&lt;EzTrigger&gt;](#eztrigger) | 트리거 목록|
| nextPageToken | string | 목록의 나머지를 취득하기 위한 페이지 토큰|

#### 구현 예제




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

```

**Unity (Vanilla)**
```cs
    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;
        }
    }

```

**Unreal Engine 5**
```cpp
    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());
    }

```


##### 값 변경 이벤트 핸들링




**Unity (UniTask)**
```csharp
    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeTriggers(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeTriggers(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeTriggers(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeTriggers(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Schedule->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    
    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->SubscribeTriggers(
        []() {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    Domain->UnsubscribeTriggers(CallbackId);

```


**⚠️ Warning**

이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.

로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.

따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.

---

### getEvent

특정 이벤트의 스케줄 상태 조회<br>

이름을 지정하여 특정 이벤트를 플레이어에 대한 현재 스케줄 상태와 함께 조회합니다.<br>
응답에는 이벤트가 현재 개최 중인지(inSchedule), 시작·종료 시각, 해당하는 경우 반복 스케줄 정보가 포함됩니다.<br>
상대 스케줄 이벤트의 경우, 종료 시각은 플레이어의 트리거를 기반으로 계산되므로, 같은 이벤트라도 플레이어에 따라 종료 시각이 다를 수 있습니다.<br>
특정 이벤트가 개최 중인지 확인하고 남은 시간을 표시하는 데 사용합니다. 예를 들어 "여름 이벤트: 남은 3일", "초보자 보너스: 남은 12시간"과 같이 카운트다운 타이머와 함께 표시하는 데 유용합니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| eventName | string |  | ✓|  |  ~ 128자 | 이벤트 이름<br>이벤트 고유의 이름. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzEvent](#ezevent) | 이벤트|
| inSchedule | bool | 현재 이벤트 기간 중인지 여부|
| scheduleStartAt | long | 이벤트 기간 시작 시각|
| scheduleEndAt | long | 이벤트 기간 종료 시각<br>이벤트 종류가 absolute 인 경우 EventModel 의 absoluteEnd 가 저장됩니다.<br>이벤트 종류가 relative 인 경우 scheduleEndAt 에는 트리거의 유효 기간 또는 EventModel 의 absoluteEnd 중 더 빨리 종료되는 쪽이 저장됩니다.|
| repeatSchedule | [EzRepeatSchedule](#ezrepeatschedule) | 반복 정보|
| isGlobalSchedule | bool | 이벤트가 글로벌 스케줄인지 여부|

#### 구현 예제




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

```

**Unity (Vanilla)**
```cs
    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;

```

**Unreal Engine 5**
```cpp
    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;
    }

```

**Godot**
```gdscript

var domain = ez.schedule.namespace_(
        "namespace-0001"
    ).me(game_session).event(
        "event-0001"
    )

var async_result = await domain.model()
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

```


##### 값 변경 이벤트 핸들링




**Unity (UniTask)**
```csharp
    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Event(
        eventName: "event-0001"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Event(
        eventName: "event-0001"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Schedule->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Event(
        "event-0001" // eventName
    );
    
    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Schedule::Model::FEvent> value) {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    Domain->Unsubscribe(CallbackId);

```

**Godot**
```gdscript

var domain = ez.schedule.namespace_(
        "namespace-0001"
    ).me(game_session).event(
        "event-0001"
    )

# 이벤트 핸들링 시작
var callback_id = domain.subscribe_model(func(value):
    # 값이 변화했을 때 호출됨
    # value에는 변경 후의 값이 전달됩니다
    pass
)

# 이벤트 핸들링 정지
domain.unsubscribe_model(callback_id)

```


**⚠️ Warning**

이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.

로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.

따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.

---

### listEvents

플레이어의 현재 개최 중인 이벤트 목록 조회<br>

이 플레이어에 대해 현재 개최 중인 모든 이벤트를 조회합니다.<br>
이벤트에는 2가지 종류가 있습니다:<br>
- 절대 스케줄 이벤트: 모든 플레이어에게 공통되는 고정 일시 이벤트 (예: "크리스마스 이벤트: 12월 24일~25일", "여름 세일: 7월 1일~31일")<br>
- 상대 스케줄 이벤트: 트리거가 활성화된 시점부터 플레이어별로 시작되는 이벤트 (예: 최초 로그인부터 시작되는 "7일간 초보자 보너스", 레벨 10 도달부터 시작되는 "24시간 한정 플래시 세일")<br>
현재 개최 기간 중인 이벤트만 반환됩니다.<br>
지금 어떤 이벤트가 개최 중인지 플레이어에게 표시할 때 사용합니다. 예를 들어 홈 화면에 이벤트 배너를 표시하거나 이벤트 전용 UI 요소를 활성화하는 경우 등에 사용합니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| items | [List&lt;EzEvent&gt;](#ezevent) | 이벤트 목록|

#### 구현 예제




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

```

**Unity (Vanilla)**
```cs
    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;
        }
    }

```

**Unreal Engine 5**
```cpp
    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());
    }

```


##### 값 변경 이벤트 핸들링




**Unity (UniTask)**
```csharp
    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeEvents(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeEvents(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Schedule.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeEvents(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeEvents(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Schedule->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    
    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->SubscribeEvents(
        []() {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    Domain->UnsubscribeEvents(CallbackId);

```


**⚠️ Warning**

이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.

로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.

따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.

---