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

# GS2-Schedule

イベントスケジュール機能




ゲーム内のイベントなどのスケジュールを管理する機能を提供します。

GS2-Schedule は単体ではイベントの期間情報のみを管理する機能を持ち、報酬の付与や購入制限といった処理は他のマイクロサービスと組み合わせて実現します。
GS2-Showcase / GS2-Exchange / GS2-LoginReward / GS2-Mission など、ほぼ全てのゲーム要素マイクロサービスがイベント期間との連携を前提に設計されているため、期間限定の運用施策を行う際の中核となるマイクロサービスです。

## イベントの開催期間

イベントの開催期間には2種類あります。
1つ目は、全てのプレイヤーが同じ期間を共有する「絶対期間」、2つ目は、プレイヤーごとに期間が異なる「相対期間」となります。

```mermaid
graph TD
  Event["イベント"]
  Event --> Absolute["絶対期間<br/>(scheduleType = absolute)"]
  Event --> Relative["相対期間<br/>(scheduleType = relative)"]
  Absolute --> AbsoluteSample["例: 1月1日〜1月3日の<br/>ニューイヤーイベント"]
  Relative --> RelativeSample["例: 初プレイから7日間<br/>初回ボス撃破から24時間"]
```

### 絶対期間

「1月1日〜1月3日でニューイヤーイベントを開催する」といったケースで使用する期間タイプです。
全プレイヤーで同一の開催期間が共有されるため、`absoluteBegin` / `absoluteEnd` をマスターデータで指定します。

### 相対期間

「ゲーム開始から1週間」や「初めてボスを倒してから24時間」のように、プレイヤーによってイベントの期間が異なるケースで使用する期間タイプです。

相対期間を実現するための「トリガー」という仕組みがあります。
トリガーを実行したあと、指定された期間（ttl）がイベントの開催期間として扱われます。

> [Gs2Schedule:TriggerByUserId アクション]()

#### トリガーの引き方の種類

トリガーを引く時に、すでにトリガーが引かれている場合のイベント期間の指定方法には複数の方式があります。

- トリガーを再起動する（renew）
- トリガーを延長する（extend）
- 何もしない（drop）
- イベントの繰り返し終了日時で有効期限を迎える（repeatCycleEnd）
- 次回の繰り返し開始日時で有効期限を迎える（repeatCycleNextStart）
- 絶対期間イベントの終了日時で有効期限を迎える（absoluteEnd）

repeatCycleEnd / repeatCycleNextStart / absoluteEnd は、繰り返し設定や絶対期間を持つイベントに合わせて有効期限を自動調整する方式です。

2020年1月1日 00:00にトリガーを引き、7日間の相対期間イベントが開始された場合、2020年1月3日 00:00にトリガーを再度引いたときの各動作は以下のようになります。

| 方式 | イベント終了日時          |                                         |
| ---- |-------------------|-----------------------------------------|
| renew | 2020年1月10日 00:00  | トリガーの起動時点 2020年1月3日 00:00に7日間を追加        |
| extend | 2020年01月14日 00:00 | すでに存在するトリガーの有効期限 2020年1月7日 00:00に7日間を追加 |
| drop | 2020年01月7日 00:00  | すでに存在するトリガーをそのまま維持                       |

### 繰り返し設定

絶対期間／相対期間ともに、`RepeatSetting` を組み合わせることで「特定の曜日や時間帯のみ有効」「数日のサイクルで有効・無効を切り替える」といった繰り返しスケジュールを表現できます。

設定可能な繰り返しタイプは以下の通りです。

| repeatType | 説明 |
| --- | --- |
| `always` | 期間中は常に有効 |
| `daily` | 毎日 指定時刻〜指定時刻の間だけ有効（`beginHour` / `endHour`） |
| `weekly` | 毎週 指定曜日〜指定曜日の間だけ有効（`beginDayOfWeek` / `endDayOfWeek`） |
| `monthly` | 毎月 指定日〜指定日の間だけ有効（`beginDayOfMonth` / `endDayOfMonth`） |
| `custom` | 任意のサイクル日数で有効・無効を繰り返す（`anchorTimestamp` / `activeDays` / `inactiveDays`） |

`custom` タイプは「アンカー日時から3日有効・4日無効」のような任意の繰り返しサイクルを表現でき、変則的な常設イベントの設計に有用です。

#### 繰り返しスケジュール状態の取得

繰り返し設定を持つイベントについては、現在および直前の繰り返しサイクルの開始日時／終了日時を `RepeatSchedule` として取得できます。
これにより、現在のサイクル内で報酬を何回受け取ったかといった集計や、次回サイクルまでの残り時間の表示が可能です。

## トランザクションアクション

GS2-Schedule では以下のトランザクションアクションを提供しています。

- 検証アクション: イベント開催期間中の検証、イベント期間外の検証、トリガーが引かれていることの検証、トリガーが引かれていないことの検証、トリガー引きからの経過時間の検証
- 消費アクション: トリガーの削除
- 入手アクション: トリガーの実行、トリガー期間の延長

「イベント開催期間の検証」を検証アクションとして利用することで、特定のイベント期間中のみ購入可能な商品や、期間限定の交換所といった制限を、トランザクション内で安全に設けることが可能になります。また、「トリガーの実行」を入手アクションとして利用することで、クエストクリア時やアイテム入手時に、そのプレイヤーだけの期間限定イベント（相対期間）を開始させるといった、動的なゲーム体験の制御が容易になります。

## マスターデータ管理

マスターデータを登録することでマイクロサービスで利用可能なデータや振る舞いを設定できます。

マスターデータの種類には以下があります。

- `EventMaster`: イベント期間と繰り返し設定

以下はマスターデータの JSON 例です。

```json
{
  "version": "2019-03-31",
  "events": [
    {
      "name": "newyear-2026",
      "metadata": "ニューイヤーイベント",
      "scheduleType": "absolute",
      "absoluteBegin": 1735660800000,
      "absoluteEnd": 1735920000000,
      "repeatType": "always"
    },
    {
      "name": "tutorial-bonus",
      "metadata": "初回プレイから7日間限定",
      "scheduleType": "relative",
      "relativeTriggerName": "tutorial-clear",
      "repeatType": "always"
    }
  ]
}
```

マスターデータの登録はマネージメントコンソールから登録する他、GitHubからデータを反映したり、GS2-Deployを使ってCIから登録するようなワークフローを組むことが可能です。

## 実装例

### トリガーを引く

トリガーを引く処理はゲームエンジン用の SDK では処理できません。

GS2-Account のアカウント作成時のスクリプト内や、GS2-Quest のクリア報酬としてトリガーを引く、といった方法で実装してください。

### 開催中のイベント一覧を取得

現在のプレイヤーから見て開催中のイベントだけが返却されます。
絶対期間で開催中、もしくは相対期間でトリガーが引かれて有効期限内にあるイベントが該当します。



**Unity**
```csharp

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

    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());
    }
```


### 特定イベントの情報を取得

特定のイベント名を指定して、そのイベントの開催期間や繰り返し設定を取得します。
`isInSchedule` を `true` にすると現在開催中のイベントのみ、`false` にするとマスターデータに登録された全てのイベントを参照できます。



**Unity**
```csharp

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

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


### トリガー一覧を取得

プレイヤーに対して引かれている相対期間トリガーの一覧と有効期限を取得できます。



**Unity**
```csharp

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

    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());
    }
```


### 繰り返しスケジュール状態の取得

繰り返し設定を持つイベントの現在の繰り返しサイクル情報を取得します。
繰り返し回数や、現在サイクルの開始日時・終了日時、直前サイクルの終了日時を確認できます。



**Unity**
```csharp

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

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


## 詳細なリファレンス

[GS2-Schedule API リファレンス](../../api_reference/schedule)