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

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

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



## 모델

### EzBuffEntryModel

버프 엔트리 모델<br>

버프의 적용량은 버프 엔트리 모델로 관리하며, 동일한 대상에 대해 여러 버프 엔트리 모델을 연결할 수 있습니다.<br>
버프 엔트리 모델의 적용 순서는 버프 엔트리 모델의 `priority` 로 관리하며, `priority` 값이 작을수록 우선순위가 높아집니다.<br>

버프의 적용 방식은 3종류가 있으며 "Rate Add", "Mul", "Value Add"가 있습니다.<br>
Rate Add 는 버프의 적용 레이트에 가산하는 명령이며, Mul 은 버프의 적용 레이트에 곱하는 명령입니다.<br>
Value Add 는 버프 보정 계산 후의 값에 가산을 수행하는 명령입니다.<br>
예를 들어 기본 레이트가 1.0 이고 Rate Add 0.2 를 설정하면 버프 적용 레이트는 1.2 가 됩니다.<br>
Mul 0.5 를 설정하면 버프 적용 레이트는 현재 레이트의 0.5배가 됩니다.<br>

버프 엔트리 모델에는 GS2-Schedule 의 이벤트를 연결할 수 있으며, 이벤트 개최 기간 중에만 버프를 적용하도록 설정하는 것도 가능합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128자 | 버프 엔트리 모델 이름<br>버프 엔트리 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 2048자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| targetType | 문자열 열거형<br>enum {<br>"model",<br>"action"<br>}<br> |  | ✓ |  |  | 버프를 적용할 대상의 종류<br>버프를 모델의 필드 값에 적용할지, 액션의 파라미터에 적용할지를 지정합니다. "Model"은 GS2 리소스 모델의 필드를 대상으로 하며, "Action"은 GS2 액션(예: 획득량이나 소비량)의 파라미터를 대상으로 합니다.model: 모델 / action: 액션 /  |
| targetModel | [EzBuffTargetModel](#ezbufftargetmodel) | {targetType} == "model" | ✓※ |  |  | 버프를 적용할 대상 모델<br>버프를 적용할 GS2 리소스 모델과 필드를 지정합니다. 모델 이름, 필드 이름, 대상 리소스를 특정하는 조건 GRN, 그리고 레이트 값이 포함됩니다.<br><br>※ targetType이(가) "model" 이면 필수 |
| targetAction | [EzBuffTargetAction](#ezbufftargetaction) | {targetType} == "action" | ✓※ |  |  | 버프를 적용할 대상 액션<br>버프를 적용할 GS2 액션과 파라미터를 지정합니다. 액션 이름, 필드 이름, 대상 리소스를 특정하는 조건 GRN, 그리고 레이트 값이 포함됩니다.<br><br>※ targetType이(가) "action" 이면 필수 |
| expression | 문자열 열거형<br>enum {<br>"rate_add",<br>"mul",<br>"value_add"<br>}<br> |  | ✓ |  |  | 버프의 적용 타입<br>버프 값을 대상에 어떻게 적용할지를 지정합니다. "Rate Add"는 보정 레이트에 가산(예: 1.0 + 0.2 = 1.2), "Mul"은 보정 레이트에 곱함(예: 레이트 * 0.5), "Value Add"는 레이트 기반 보정 계산 후의 값에 직접 가산합니다.rate_add: 보정 레이트에 가산 / mul: 보정 레이트에 곱함 / value_add: 값을 직접 가산(모델이나 액션의 숫자 값만) /  |
| applyPeriodScheduleEventId | string |  |  |  |  ~ 1024자 | 버프를 적용할 이벤트의 개최 기간 GRN<br>이 버프의 유효 기간을 제어하는 GS2-Schedule 이벤트의 GRN입니다. 지정한 경우, 이벤트 개최 기간 중에만 버프가 적용됩니다. 지정하지 않은 경우, 버프는 항상 유효합니다. |

**관련 메서드:**
getBuffEntryModel - 이름으로 버프 정의 조회
listBuffEntryModels - 버프 엔트리 모델 목록 조회
applyBuff - 현재 플레이어에게 버프 적용


---

### EzBuffTargetModel

버프 적용 대상 모델<br>

버프 적용의 대상이 되는 GS2 리소스 모델과 필드를 정의합니다. 어떤 모델의 어떤 필드 값을 버프로 변경할지 지정하며, 대상 리소스 인스턴스를 특정하는 조건 GRN과 적용할 레이트 값을 포함합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| targetModelName | 문자열 열거형<br>enum {<br>}<br> |  | ✓ |  |  | 버프를 적용할 모델의 종류 |
| targetFieldName | string |  | ✓ |  |  ~ 64자 | 버프 적용 대상 필드명<br>버프에 의해 값이 변경되는 대상 모델 상의 수치 필드명입니다. 예를 들어 경험치나 공격력 등의 수치 속성을 나타내는 필드가 대상이 됩니다. |
| conditionGrns | [List&lt;EzBuffTargetGrn&gt;](#ezbufftargetgrn) |  | ✓ |  | 1 ~ 10 items | 버프 적용 조건 GRN 목록<br>버프 적용의 대상 리소스 인스턴스를 특정하는 GRN 패턴의 목록입니다. 여러 GRN을 조합하여 리소스를 정확하게 특정하는 복합 조건을 구성합니다. |
| rate | float |  | ✓ |  | 0 ~ 1000000 | 보정 레이트<br>적용되는 버프 값입니다. 적용 타입에 따라 의미가 다릅니다. "Rate Add"의 경우 기본 레이트에 가산, "Mul"의 경우 현재 레이트에 곱셈, "Value Add"의 경우 레이트 계산 후의 필드 값에 직접 가산됩니다. |


**관련 모델:**
EzBuffEntryModel - 버프 엔트리 모델



---

### EzBuffTargetAction

버프 적용 대상 액션<br>

버프 적용의 대상이 되는 GS2 액션과 파라미터를 정의합니다. 어떤 액션의 어떤 파라미터를 버프로 변경할지 지정하며, 대상 리소스 인스턴스를 특정하는 조건 GRN과 적용할 레이트 값을 포함합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| targetActionName | 문자열 열거형<br>enum {<br>}<br> |  | ✓ |  |  | 버프를 적용할 액션의 종류 |
| targetFieldName | string |  | ✓ |  |  ~ 64자 | 버프 적용 대상 필드명<br>버프에 의해 값이 변경되는 대상 액션 상의 수치 파라미터명입니다. 예를 들어 입수 수량, 소비량, 보상 수량 등을 나타내는 파라미터가 대상이 됩니다. |
| conditionGrns | [List&lt;EzBuffTargetGrn&gt;](#ezbufftargetgrn) |  | ✓ |  | 1 ~ 10 items | 버프 적용 조건 GRN 목록<br>버프 적용의 대상 리소스 인스턴스를 특정하는 GRN 패턴의 목록입니다. 여러 GRN을 조합하여 리소스를 정확하게 특정하는 복합 조건을 구성합니다. |
| rate | float |  | ✓ |  | 0 ~ 1000000 | 보정 레이트<br>적용되는 버프 값입니다. 적용 타입에 따라 의미가 다릅니다. "Rate Add"의 경우 기본 레이트에 가산, "Mul"의 경우 현재 레이트에 곱셈, "Value Add"의 경우 레이트 계산 후의 파라미터 값에 직접 가산됩니다. |


**관련 모델:**
EzBuffEntryModel - 버프 엔트리 모델



---

### EzBuffTargetGrn

버프 적용 조건이 되는 리소스의 GRN 패턴<br>

버프가 유효해지는 리소스 인스턴스를 좁히기 위한 조건 GRN 패턴입니다.<br>
targetModelName 으로 GS2 서비스 모델의 종류를 특정하며, targetGrn 에는 런타임에 해결되는 컨텍스트 변수({region}, {ownerId})를 포함할 수 있습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| targetModelName | string |  | ✓ |  |  ~ 64자 | 버프 적용 조건의 모델 이름<br>조건 GRN을 해결하기 위해 사용되는 GS2 서비스 모델의 이름입니다. GRN 패턴이 어느 서비스의 리소스 모델을 참조하는지를 특정합니다. |
| targetGrn | string |  | ✓ |  |  ~ 1024자 | 버프의 적용 조건 GRN<br>런타임에 해결되는 컨텍스트 플레이스홀더(예: {region}, {ownerId})를 포함한 GRN 템플릿입니다. 버프의 대상이 되는 특정 리소스 인스턴스를 특정하기 위해 사용됩니다. |


**관련 모델:**
EzBuffTargetModel - 버프 적용 대상 모델
EzBuffTargetAction - 버프 적용 대상 액션



---

## 메서드

### getBuffEntryModel

이름으로 버프 정의 조회<br>

이름을 지정하여 버프 엔트리 모델을 1건 조회합니다.<br>
조회되는 정보에는 적용 방법(Rate Add / Mul / Value Add), 버프의 대상,<br>
우선순위, 그리고 설정되어 있는 경우 버프가 활성화되는 이벤트 기간이 포함됩니다.<br>

특정 버프의 효과 내용이나 활성 기간 등의 상세 정보를 표시할 때 사용합니다.

#### Request

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

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzBuffEntryModel](#ezbuffentrymodel) | 버프 엔트리 모델|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Buff.Namespace(
        namespaceName: "namespace-0001"
    ).BuffEntryModel(
        buffEntryName: "character-level"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Buff.Namespace(
        namespaceName: "namespace-0001"
    ).BuffEntryModel(
        buffEntryName: "character-level"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Buff->Namespace(
        "namespace-0001" // namespaceName
    )->BuffEntryModel(
        "character-level" // buffEntryName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```

**Godot**
```gdscript

var domain = ez.buff.namespace_(
        "namespace-0001"
    ).buff_entry_model(
        "character-level"
    )

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

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

```

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

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

```

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

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

```

**Godot**
```gdscript

var domain = ez.buff.namespace_(
        "namespace-0001"
    ).buff_entry_model(
        "character-level"
    )

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

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

---

### listBuffEntryModels

버프 엔트리 모델 목록 조회<br>

이 네임스페이스에 등록된 모든 버프 엔트리 모델을 조회합니다.<br>
각 버프 엔트리 모델은 하나의 버프 효과를 정의합니다.<br>
대상(모델의 스탯이나 액션의 파라미터), 적용 방법(Rate Add / Mul / Value Add), 우선순위,<br>
그리고 선택적으로 버프가 활성화되는 이벤트 기간이 포함됩니다.<br>

게임 UI에서 버프 목록을 표시하거나, 현재 설정된 버프를 확인할 때 사용합니다.

#### Request

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

#### Result

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

#### 구현 예제




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

```

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

```


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




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

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

```

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

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

```

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

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

```


**⚠️ Warning**

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

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

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

---

### applyBuff

현재 플레이어에게 버프 적용<br>

이 네임스페이스에 등록된 모든 버프 설정을 평가하여, 조건에 맞는 것을 플레이어에게 적용합니다.<br>
예를 들어 "이벤트 중 경험치 2배", "특정 아이템 소지 시 골드 드롭률 +10%"와 같은 버프를 설정할 수 있습니다.<br>

버프의 적용 방법은 3가지가 있습니다:<br>
- **Rate Add**: 배율에 가산합니다(예: 기본 1.0 + 0.2 = 1.2배)<br>
- **Mul**: 현재 배율에 곱합니다(예: 배율 × 0.5)<br>
- **Value Add**: 배율 계산 후의 값에 고정값을 가산합니다<br>

GS2-Schedule 이벤트에 연동된 버프는 해당 이벤트 개최 기간 동안만 유효합니다.<br>
여러 버프는 우선순위 순서로 적용됩니다(값이 작을수록 우선순위가 높음).

#### Request

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

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| items | [List&lt;EzBuffEntryModel&gt;](#ezbuffentrymodel) | 적용한 버프 목록|
| newContextStack | string | 버프의 적용 상태를 기록한 컨텍스트|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Buff.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Buff(
    );
    var result = await domain.ApplyBuffAsync(
    );
    var item = await result.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Buff.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Buff(
    );
    var future = domain.ApplyBuffFuture(
    );
    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->Buff->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Buff(
    );
    const auto Future = Domain->ApplyBuff(
    );
    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.buff.namespace_(
        "namespace-0001"
    ).me(game_session).buff(
    )

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

var result = async_result.result

```


---