GS2-Enchant

장비나 캐릭터에 고유한 랜덤 파라미터를 부여하는 기능을 구현합니다. RPG에서의 무기 추가 스탯, 가챠로 입수한 카드에 부여되는 개체값, 핵앤슬래시 계열에서의 장비 추가 효과 등, “같은 아이템이라도 개체마다 성능이 다르다"는 표현을 구현할 때 활용할 수 있습니다.

랜덤 파라미터에는 2가지 종류를 준비하고 있습니다.

• 밸런스 파라미터
• 레어리티 파라미터

graph TD
  Item["장비·캐릭터 등<br/>(propertyId 로 식별)"] --> Choose{파라미터 종류}
  Choose -- 총량을 분배 --> Balance["밸런스 파라미터<br/>예: 공격력60/방어력40"]
  Choose -- 확률로 복수 부여 --> Rarity["레어리티 파라미터<br/>예: 크리티컬율+5%, HP+100"]
  Balance --> ReDraw1["재추첨 / 값 직접 설정"]
  Rarity --> ReDraw2["재추첨 / 추가 / 값 직접 설정"]

랜덤 파라미터는 “대상 아이템의 식별자"가 되는 propertyId를 키로 하여 관리됩니다. propertyId에는 GS2-Inventory의 아이템 인스턴스ID나 GS2-Formation의 폼 식별자 등을 지정함으로써, 장비 개체마다 파라미터를 연결할 수 있습니다.

밸런스 파라미터

밸런스 파라미터는 준비된 여러 파라미터에 정해진 총량을 랜덤으로 분배합니다. 예를 들어 공격력과 방어력이라는 2개의 파라미터를 준비하고 총량을 100으로 설정한 경우, 공격력이 60으로 추첨되면 방어력은 40이 됩니다.

재추첨

밸런스 파라미터는 재추첨이 가능합니다. 재추첨을 수행할 때 일부 파라미터의 값을 고정할 수 있습니다. 파라미터를 일부 고정함으로써, 플레이어가 파라미터 최적화를 효율적으로 수행할 수 있는 수단을 제공할 수 있습니다.

초기값

밸런스 파라미터의 초기값은 랜덤 값으로 할지, 평균값으로 할지를 정할 수 있습니다.

값 직접 설정

밸런스 파라미터는 관리 화면이나 API(트랜잭션 액션)를 통해 추첨을 거치지 않고 임의의 값을 직접 설정하는 것도 가능합니다. 이를 통해 특정 이벤트 보상으로 고정된 스탯을 가진 장비를 배포하는 등의 운용이 가능해집니다.

레어리티 파라미터

레어리티 파라미터는 밸런스 파라미터처럼 일정한 파라미터에 값을 분배하는 것이 아니라, 장비나 스킬에 일정 확률로 추가 파라미터를 부여하는 경우에 사용할 수 있습니다.

마스터 데이터에는 먼저 파라미터를 부여할 개수의 추첨 확률을 설정합니다. 다음으로, 부여할 파라미터의 종류와 확률을 설정합니다. 이렇게 하면 확률에 기반하여 추가 파라미터를 부여할 수 있게 됩니다.

각 파라미터(RarityParameterValueModel)에는 resourceName/resourceValue를 설정할 수 있으며, 부여된 결과로서 어떤 리소스를 얼마나 참조하고 있는지를 표현할 수 있습니다.

재추첨

부여된 파라미터는 재추첨이 가능하며, 재추첨 시에는 부여된 파라미터의 종류만 변동하고 개수는 변하지 않습니다. 밸런스 파라미터와 마찬가지로, 재추첨하는 파라미터 중 일부 파라미터를 고정할 수 있습니다.

추가

레어리티 파라미터는 나중에 추가할 수 있습니다. 추가할 때는 이미 있는 파라미터는 변경하지 않고, 지정된 개수의 파라미터를 추가할 수 있습니다.

값 직접 설정

레어리티 파라미터는 관리 화면이나 API(트랜잭션 액션)를 통해 부여되어 있는 파라미터의 종류나 그 값을 직접 설정하는 것도 가능합니다. 이를 통해 밸런스 파라미터와 마찬가지로, 특정 성능이 보장된 아이템의 배포 등이 가능해집니다.

트랜잭션 액션

GS2-Enchant에서는 다음과 같은 트랜잭션 액션을 제공하고 있습니다. 이를 이용함으로써 퀘스트 보상이나 상점 구매 등을 통해 파라미터 조작을 수행할 수 있습니다.

검증 액션

입수 액션

마스터 데이터 운용

마스터 데이터를 등록함으로써 마이크로서비스에서 사용할 수 있는 데이터와 동작을 설정할 수 있습니다.

마스터 데이터의 종류에는 다음이 있습니다.

• BalanceParameterModel: 파라미터 분배 설정
• RarityParameterModel: 부여 파라미터와 확률 설정

다음은 마스터 데이터 JSON의 예시입니다.

{
  "version": "2023-04-27",
  "balanceParameterModels": [
    {
      "name": "balance-0001",
      "metadata": "weapon",
      "totalValue": 100,
      "initialValueStrategy": "average",
      "parameters": [
        { "name": "attack", "metadata": "ATK" },
        { "name": "defense", "metadata": "DEF" }
      ]
    }
  ],
  "rarityParameterModels": [
    {
      "name": "rarity-0001",
      "metadata": "weapon",
      "maximumParameterCount": 4,
      "parameterCounts": [
        { "count": 1, "weight": 70 },
        { "count": 2, "weight": 25 },
        { "count": 3, "weight": 5 }
      ],
      "parameters": [
        { "name": "critical", "weight": 50, "resourceName": "critical", "resourceValue": 5 },
        { "name": "hp", "weight": 50, "resourceName": "hp", "resourceValue": 100 }
      ]
    }
  ]
}

마스터 데이터 등록은 매니지먼트 콘솔에서 등록하는 것 외에도, GitHub에서 데이터를 반영하거나 GS2-Deploy를 사용해 CI에서 등록하는 워크플로우를 구성하는 것도 가능합니다.

구현 예제

밸런스 파라미터

파라미터 초기화/취득

처음으로 파라미터 정보를 취득할 때 파라미터 추첨 처리가 생성됩니다.

• Game Engine:
• Unity
• Unreal Engine
• Godot

    var item = await gs2.Enchant.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).BalanceParameterStatus(
        parameterName: "balance-0001",
        propertyId: "property-0001"
    ).ModelAsync();

    const auto item = Gs2->Enchant->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->BalanceParameterStatus(
        "balance-0001", // parameterName
        "property-0001" // propertyId
    ).Model();

var domain = ez.enchant.namespace_(
        "namespace-0001"
    ).me(game_session).balance_parameter_status(
        "balance-0001",
        "property-0001"
    )

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

var result = async_result.result

파라미터 값 참조

ModelAsync로 취득한 EzBalanceParameterStatus의 ParameterValues에서 각 파라미터명과 현재 값을 취득할 수 있습니다.

• Game Engine:
• Unity
• Unreal Engine
• Godot

    foreach (var parameterValue in item.ParameterValues) {
        Debug.Log($"{parameterValue.Name} = {parameterValue.Value}");
    }

    for (auto ParameterValue : *item->ParameterValues) {
        UE_LOG(LogTemp, Log, TEXT("%s = %lld"), *ParameterValue->Name, ParameterValue->Value);
    }

for parameter_value in item.parameter_values:
    print(parameter_value.name, " = ", parameter_value.value)

파라미터 재추첨

재추첨은 게임 엔진용 SDK로는 처리할 수 없습니다. 게임 내에서는 GS2-Distributor를 경유하여 Gs2Enchant:ReDrawBalanceParameterStatusByUserId 등의 트랜잭션 액션을 실행함으로써 재추첨을 수행해 주시기 바랍니다.

레어리티 파라미터

파라미터 초기화/취득

처음으로 파라미터 정보를 취득할 때 파라미터 추첨 처리가 생성됩니다.

• Game Engine:
• Unity
• Unreal Engine
• Godot

    var item = await gs2.Enchant.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RarityParameterStatus(
        parameterName: "rarity-0001",
        propertyId: "property-0001"
    ).ModelAsync();

    const auto item = Gs2->Enchant->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->RarityParameterStatus(
        "rarity-0001", // parameterName
        "property-0001" // propertyId
    ).Model();

var domain = ez.enchant.namespace_(
        "namespace-0001"
    ).me(game_session).rarity_parameter_status(
        "rarity-0001",
        "property-0001"
    )

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

var result = async_result.result

파라미터 검증

레어리티 파라미터가 부여되어 있는지, 혹은 특정 개수가 부여되어 있는지를 서버에서 검증하도록 할 수 있습니다. 가챠나 강화 처리에서 “특정 파라미터를 가진 장비만 허용한다"와 같은 조건 확인에 사용할 수 있습니다.

• Game Engine:
• Unity
• Unreal Engine
• Godot

    var domain = await gs2.Enchant.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RarityParameterStatus(
        parameterName: "rarity-0001",
        propertyId: "property-0001"
    ).VerifyRarityParameterStatusAsync(
        verifyType: "have",
        parameterValueName: "critical",
        parameterCount: 1
    );

    const auto Future = Gs2->Enchant->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->RarityParameterStatus(
        "rarity-0001", // parameterName
        "property-0001" // propertyId
    )->VerifyRarityParameterStatus(
        "have", // verifyType
        "critical", // parameterValueName
        1 // parameterCount
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError()) return false;

var domain = ez.enchant.namespace_(
        "namespace-0001"
    ).me(game_session).rarity_parameter_status(
        "rarity-0001",
        "property-0001"
    )

var async_result = await domain.verify_rarity_parameter_status(
    "have", # verify_type
    "parameter-0001", # parameter_value_name
    null # parameter_count
)
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

파라미터 재추첨

재추첨은 게임 엔진용 SDK로는 처리할 수 없습니다. 게임 내에서는 GS2-Distributor를 경유하여 Gs2Enchant:ReDrawRarityParameterStatusByUserId 등의 트랜잭션 액션을 실행함으로써 재추첨을 수행해 주시기 바랍니다.

파라미터 추가

파라미터 추가는 게임 엔진용 SDK로는 처리할 수 없습니다. GS2-Distributor를 경유하여 Gs2Enchant:AddRarityParameterStatusByUserId를 실행함으로써 추가해 주시기 바랍니다.

상세 레퍼런스