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

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

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



## 모델

### EzEntry

게임 플레이어가 획득한 엔트리<br>

게임 플레이어가 수집한 도감 엔트리 1건을 나타냅니다. 각 엔트리는 EntryModel에 대응하며, 획득 일시를 기록합니다. 보유 상태는 '존재함(수집됨) / 존재하지 않음'의 2가지 값으로 관리되며, 수량의 개념은 없습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| entryId | string |  | ※ |  |  ~ 1024자 | 엔트리 GRN<br>※ 서버가 자동으로 설정 |
| userId | string |  |  |  |  ~ 128자 | 사용자ID |
| name | string |  | ✓ |  |  ~ 128자 | 엔트리 모델 이름<br>엔트리 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. |
| acquiredAt | long |  | ※ | 현재 시각 |  | 획득 일시<br>이 엔트리가 게임 플레이어에 의해 처음 수집된 일시입니다. 등록 시 현재 시각이 자동으로 설정되며, 이후 변경할 수 없습니다. |

**관련 메서드:**
getEntry - 플레이어가 특정 엔트리를 수집했는지 확인
getEntryWithSignature - 변조 방지 서명이 포함된 엔트리 가져오기
listEntries - 플레이어가 수집한 엔트리 목록 조회


---

### EzLike

즐겨찾기로 등록한 엔트리<br>

게임 플레이어가 즐겨찾기(좋아요)로 등록한 도감 엔트리를 나타냅니다. 플레이어가 도감 내 특정 엔트리를 북마크하여 빠르게 접근할 수 있도록 합니다. 각 즐겨찾기는 EntryModel을 이름으로 참조하며, 사용자별로 고유합니다. 동일한 엔트리를 중복하여 즐겨찾기에 등록할 수 없습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| likeId | string |  | ※ |  |  ~ 1024자 | 즐겨찾기 엔트리 GRN<br>※ 서버가 자동으로 설정 |
| userId | string |  |  |  |  ~ 128자 | 사용자ID |
| name | string |  | ✓ |  |  ~ 128자 | 엔트리 모델 이름<br>엔트리 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. |

**관련 메서드:**
addLikes - 엔트리를 즐겨찾기에 추가
deleteLikes - 엔트리를 즐겨찾기에서 제외
getLike - 특정 엔트리가 즐겨찾기인지 확인
listLikes - 플레이어의 즐겨찾기 엔트리 목록 조회


---

### EzEntryModel

엔트리 모델<br>

엔트리 모델은 GS2-Dictionary에서 도감에 기록 가능한 대상을 정의하는 마스터 데이터입니다.<br>
각 엔트리 모델은 몬스터, 아이템, 아바타 파츠 등 도감에 기록되는 엔티티의 종류를 나타냅니다.<br>

엔트리의 보유 상태는 '기록됨 / 미기록'의 2가지 값으로 관리되며, 동일한 엔트리 모델에 대해 수량이나 스택의 개념은 없습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128자 | 엔트리 모델 이름 |
| metadata | string |  |  |  |  ~ 2048자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |

**관련 메서드:**
getEntryModel - 이름을 지정하여 수집 아이템 정의 조회
listEntryModels - 수집 아이템 정의 목록 조회


---

### EzConfig

설정<br>

분산 트랜잭션 실행 시 트랜잭션 변수에 적용되는 키와 값의 쌍입니다. 실행 시점에 트랜잭션 파라미터 내의 플레이스홀더 값을 동적으로 치환할 수 있습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| key | string |  | ✓ |  |  ~ 64자 | 이름<br>트랜잭션 파라미터 내에서 플레이스홀더 키로 사용되는 변수 이름입니다. 트랜잭션 템플릿에 정의된 플레이스홀더와 일치해야 합니다. |
| value | string |  |  |  |  ~ 51200자 | 값<br>트랜잭션 실행 시 플레이스홀더 키에 대입할 값입니다. 트랜잭션 파라미터 내의 해당 플레이스홀더가 이 값으로 치환됩니다. |


---

## 메서드

### getEntryModel

이름을 지정하여 수집 아이템 정의 조회<br>

이름을 지정하여 엔트리 모델을 1건 조회합니다.<br>
플레이어가 도감 화면에서 엔트리를 탭했을 때, 해당 아이템의 설명이나 메타데이터 등 상세 정보를 표시할 때 사용합니다.

#### Request

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

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzEntryModel](#ezentrymodel) | 엔트리 모델|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    ).EntryModel(
        entryName: "entry-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    ).EntryModel(
        entryName: "entry-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Dictionary->Namespace(
        "namespace-0001" // namespaceName
    )->EntryModel(
        "entry-0001" // entryName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```

**Godot**
```gdscript

var domain = ez.dictionary.namespace_(
        "namespace-0001"
    ).entry_model(
        null
    )

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.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    ).EntryModel(
        entryName: "entry-0001"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

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

```

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

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

```

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

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

```

**Godot**
```gdscript

var domain = ez.dictionary.namespace_(
        "namespace-0001"
    ).entry_model(
        null
    )

# 이벤트 핸들링 시작
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의 실행에 의해 변화한 것만이 대상이 됩니다.

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

---

### listEntryModels

수집 아이템 정의 목록 조회<br>

이 네임스페이스에 등록된 모든 엔트리 모델(수집 가능한 아이템의 종류)을 조회합니다.<br>
엔트리 모델은 플레이어의 컬렉션에 등장하는 아이템을 정의합니다. 예를 들어 도감의 몬스터, 앨범의 캐릭터, 업적 등입니다.<br>
컬렉션 화면이나 도감 화면에서 수집 가능한 아이템의 전체 목록을 표시할 때 사용합니다.

#### Request

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

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| items | [List&lt;EzEntryModel&gt;](#ezentrymodel) | 엔트리 모델 목록|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.EntryModelsAsync(
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.EntryModels(
    );
    List<EzEntryModel> items = new List<EzEntryModel>();
    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->Dictionary->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->EntryModels(
    );
    TArray<Gs2::UE5::Dictionary::Model::FEzEntryModelPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

```


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




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

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

```

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

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

```

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

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

```


**⚠️ Warning**

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

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

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

---

### getEntry

플레이어가 특정 엔트리를 수집했는지 확인<br>

엔트리 모델 이름을 지정하여, 플레이어가 특정 수집 아이템을 획득했는지 여부를 확인합니다.<br>
도감의 아이템 상세 화면에서 "수집 완료" 또는 "미수집" 상태를 표시할 때 사용합니다.

#### Request

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

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzEntry](#ezentry) | 엔트리|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Entry(
        entryModelName: "entry-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Entry(
        entryModelName: "entry-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Dictionary->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Entry(
        "entry-0001" // entryModelName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```

**Godot**
```gdscript

var domain = ez.dictionary.namespace_(
        "namespace-0001"
    ).me(game_session).entry(
        "entry-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.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Entry(
        entryModelName: "entry-0001"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

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

```

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

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

```

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

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

```

**Godot**
```gdscript

var domain = ez.dictionary.namespace_(
        "namespace-0001"
    ).me(game_session).entry(
        "entry-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의 실행에 의해 변화한 것만이 대상이 됩니다.

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

---

### getEntryWithSignature

변조 방지 서명이 포함된 엔트리 가져오기<br>

데이터가 변조되지 않았음을 증명하는 암호 서명과 함께 엔트리를 가져옵니다.<br>
플레이어가 특정 컬렉션 엔트리를 실제로 보유하고 있는지 외부 서버에서 검증하고 싶을 때 사용합니다.<br>
예를 들어, 컬렉션 진행 상황에 따라 커스텀 서버에서 보상을 지급하는 경우 등에 유용합니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |
| entryModelName | string |  | ✓|  |  ~ 128자 | 엔트리 모델 이름<br>엔트리 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. |
| keyId | string |  | | "grn:gs2:{region}:{ownerId}:key:default:key:default" |  ~ 1024자 | 암호화 키 GRN |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzEntry](#ezentry) | 엔트리|
| body | string | 서명 대상 엔트리 정보|
| signature | string | 서명|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Entry(
        entryModelName: "entry-0001"
    );
    var result = await domain.GetEntryWithSignatureAsync(
        keyId: "key-0001"
    );
    var item = await result.ModelAsync();
    var body = result.Body;
    var signature = result.Signature;

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Entry(
        entryModelName: "entry-0001"
    );
    var future = domain.GetEntryWithSignatureFuture(
        keyId: "key-0001"
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;
    var body = future.Result.Body;
    var signature = future.Result.Signature;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Dictionary->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Entry(
        "entry-0001" // entryModelName
    );
    const auto Future = Domain->GetEntryWithSignature(
        "key-0001" // keyId
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // 변경된 값 / 결과 값을 취득
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();
    const auto Body = Result->Body;
    const auto Signature = Result->Signature;

```

**Godot**
```gdscript

var domain = ez.dictionary.namespace_(
        "namespace-0001"
    ).me(game_session).entry(
        "entry-0001"
    )

var async_result = await domain.get_entry_with_signature(
    "key-0001" # key_id
)
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

```


---

### listEntries

플레이어가 수집한 엔트리 목록 조회<br>

플레이어가 지금까지 획득한 엔트리(수집 아이템)의 목록을 조회합니다.<br>
플레이어가 잠금 해제한 아이템을 표시하는 컬렉션 화면이나 도감 화면을 구성할 때 사용합니다.<br>
이 목록을 엔트리 모델의 전체 목록과 비교하면, 수집한 아이템과 수집하지 않은 아이템을 표시할 수 있습니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |
| limit | int |  | | 30 | 1 ~ 10000 | 취득할 데이터 건수 |
| pageToken | string |  | |  |  ~ 1024자 | 데이터 취득을 시작할 위치를 지정하는 토큰 |

#### Result

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

#### 구현 예제




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

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Entries(
    );
    List<EzEntry> items = new List<EzEntry>();
    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->Dictionary->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->Entries(
    );
    TArray<Gs2::UE5::Dictionary::Model::FEzEntryPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

```


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




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

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

```

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

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

```

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

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

```


**⚠️ Warning**

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

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

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

---

### addLikes

엔트리를 즐겨찾기에 추가<br>

하나 이상의 엔트리를 플레이어의 즐겨찾기로 등록합니다.<br>
여러 엔트리 이름을 한 번에 지정하여 일괄로 즐겨찾기에 추가할 수 있습니다.<br>
이미 즐겨찾기에 등록된 엔트리는 그대로 건너뜁니다(오류가 발생하지 않습니다).<br>
컬렉션 화면에서 플레이어가 "즐겨찾기" 버튼을 탭했을 때 사용합니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |
| entryModelNames | List&lt;string&gt; |  | | [] | 0 ~ 100 items | 엔트리 모델 이름 목록 |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| items | [List&lt;EzLike&gt;](#ezlike) | 등록한 즐겨찾기 엔트리 목록|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var result = await domain.AddLikesAsync(
        entryModelNames: new List<string> {
            "entry-0001",
            "entry-0002",
            "entry-0003",
        }
    );
    var item = await result.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var future = domain.AddLikesFuture(
        entryModelNames: new List<string> {
            "entry-0001",
            "entry-0002",
            "entry-0003",
        }
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Dictionary->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto Future = Domain->AddLikes(
        []
        {
            auto v = TOptional<TArray<FString>>();
            v->Add("entry-0001");
            v->Add("entry-0002");
            v->Add("entry-0003");
            return v;
        }() // entryModelNames
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // 변경된 값 / 결과 값을 취득
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

```

**Godot**
```gdscript

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

var async_result = await domain.add_likes(
    [
        "entry-0001",
        "entry-0002",
        "entry-0003",
    ] # entry_model_names
)
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

```


---

### deleteLikes

엔트리를 즐겨찾기에서 제외<br>

플레이어의 즐겨찾기 목록에서 하나 이상의 엔트리를 삭제합니다.<br>
여러 엔트리 이름을 한 번에 지정하여 일괄로 즐겨찾기에서 제외할 수 있습니다.<br>
컬렉션 화면에서 플레이어가 "즐겨찾기 해제" 버튼을 탭했을 때 사용합니다.<br>
엔트리의 수집 상태에는 영향을 주지 않습니다. 수집된 상태는 그대로 유지됩니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |
| entryModelNames | List&lt;string&gt; |  | | [] | 0 ~ 100 items | 엔트리 모델 이름 목록 |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| items | [List&lt;EzLike&gt;](#ezlike) | 삭제한 즐겨찾기 엔트리 목록|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var result = await domain.DeleteLikesAsync(
        entryModelNames: new List<string> {
            "entry-0001",
            "entry-0002",
            "entry-0003",
        }
    );

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var future = domain.DeleteLikesFuture(
        entryModelNames: new List<string> {
            "entry-0001",
            "entry-0002",
            "entry-0003",
        }
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Dictionary->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto Future = Domain->DeleteLikes(
        []
        {
            auto v = TOptional<TArray<FString>>();
            v->Add("entry-0001");
            v->Add("entry-0002");
            v->Add("entry-0003");
            return v;
        }() // entryModelNames
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();

```

**Godot**
```gdscript

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

var async_result = await domain.delete_likes(
    [
        "entry-0001",
        "entry-0002",
        "entry-0003",
    ] # entry_model_names
)
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

```


---

### getLike

특정 엔트리가 즐겨찾기인지 확인<br>

플레이어가 특정 엔트리를 즐겨찾기에 등록했는지 확인합니다.<br>
도감의 아이템 상세 화면에서 "즐겨찾기 등록됨" 아이콘이나 하이라이트를 표시할 때 사용합니다.

#### Request

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

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzLike](#ezlike) | 즐겨찾기 엔트리|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Like(
        entryModelName: "entry-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Like(
        entryModelName: "entry-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Dictionary->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Like(
        "entry-0001" // entryModelName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```

**Godot**
```gdscript

var domain = ez.dictionary.namespace_(
        "namespace-0001"
    ).me(game_session).like(
        "entry-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.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Like(
        entryModelName: "entry-0001"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

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

```

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

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

```

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

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

```

**Godot**
```gdscript

var domain = ez.dictionary.namespace_(
        "namespace-0001"
    ).me(game_session).like(
        "entry-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의 실행에 의해 변화한 것만이 대상이 됩니다.

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

---

### listLikes

플레이어의 즐겨찾기 엔트리 목록 조회<br>

플레이어가 즐겨찾기에 등록한 엔트리의 목록을 조회합니다.<br>
즐겨찾기는 수집과는 별도로 관리됩니다. 엔트리를 수집해도 자동으로 즐겨찾기에 등록되지는 않습니다.<br>
컬렉션 화면의 "즐겨찾기" 탭을 표시하여, 플레이어가 관심 있는 아이템에 빠르게 접근할 수 있도록 할 때 사용합니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| gameSession | GameSession | | ✓|  |  | GameSession |
| limit | int |  | | 30 | 1 ~ 1000 | 취득할 데이터 건수 |
| pageToken | string |  | |  |  ~ 1024자 | 데이터 취득을 시작할 위치를 지정하는 토큰 |

#### Result

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

#### 구현 예제




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

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Likes(
    );
    List<EzLike> items = new List<EzLike>();
    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->Dictionary->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->Likes(
    );
    TArray<Gs2::UE5::Dictionary::Model::FEzLikePtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

```


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




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

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

```

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

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

```

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

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

```


**⚠️ Warning**

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

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

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

---