Skip to main content

플레이어 인벤토리

요구 사항

플레이어 인벤토리를 사용하려면 타이틀에 대해 카탈로그가 정의되어 있어야 합니다. 자세한 내용은 Catalogs 자습서를 참조하세요.
선택적으로 카탈로그에 대해 스토어를 정의할 수도 있습니다.
카탈로그가 게임에서 사용 가능한 모든 아이템의 목록인 반면, 스토어는 고유한 가격 책정 옵션이 있는 카탈로그의 아이템 하위 집합입니다. 카탈로그당 여러 스토어를 정의할 수 있으므로, 사용자 세그멘테이션 또는 기타 요인에 따라 플레이어에게 제시할 별개의 아이템 세트를 가질 수 있습니다. Game Manager를 통해, 또는 관리자 SetCatalogItems 또는 UpdateCatalogItems API 호출을 통해 카탈로그를 정의하면 클라이언트와 서버에서 다양한 인벤토리 API 호출을 사용할 수 있습니다.

API 개요

모든 인벤토리 API 호출은 서버 권한 기반으로 안전하게 설계되었습니다. 올바르게 사용하면 고객이 부정 행위를 하거나 획득하지 않은 아이템을 얻을 수 없습니다. 클라이언트: 서버: 아래 표시된 예제는 이러한 API 메서드를 호출하는 코드 블록을 보여주고 플레이어 인벤토리에 대한 기본 사용 사례를 설정합니다.
참고로 이 예제들은 PlayFab 기능을 시연하기 위해 만든 예제 게임인 Unicorn Battle에서 가져온 것입니다.
아래에서 사용된 AU 가상 통화는 Gold로, 몬스터와 싸워 얻는 무료 통화입니다(Currencies 자습서 참조). 시작하기 전에, 이 가이드의 대부분의 예제에서 사용되고 재사용될 몇 가지 유틸리티 함수를 정의합니다.

클라이언트 전용 예제: 체력 물약 구매 및 소비

클라이언트 API 호출 순서: PurchaseItem, GetUserInventory, ConsumeItem 먼저 카탈로그에서 아이템을 정의해야 합니다. Health Potion에 대한 CatalogItem 요구 사항은 다음과 같습니다.
  • PurchaseItem은 양수의 아이템 가격이 필요합니다(5 AU).
  • ConsumeItem은 아이템이 Consumable이어야 하며, 양수 아이템 카운트(3)가 있어야 합니다.
  • 구매하는 플레이어는 가상 통화 잔액에 5 AU 이상이 있어야 합니다.
각 호출의 코드는 아래에 제공됩니다.

예제: 플레이어에게 컨테이너가 부여되고 열림

API 호출 순서: 먼저 카탈로그에 컨테이너가 정의되어 있어야 합니다. 이 예제의 컨테이너에는 CrystalContainer를 선택했습니다. 이 예제는 또한 키로 컨테이너를 여는 것을 시연합니다. 이는 UnlockContainerInstance 호출이 성공하려면 플레이어 인벤토리에도 있어야 하는 선택적 아이템입니다. 이 예제에서 CrystalContainer에 대한 CatalogItem 요구 사항은 다음과 같습니다:
  • CrystalContainerContainer로 정의해야 합니다.
  • Containers는 선택적으로 Key Item을 정의할 수 있으며, 이는 Container를 잠금 해제하는 데 필요합니다. 이 경우에는 CrystalKey입니다.
  • Container와 모든 Key모두 Consumable로 정의하는 것을 강력히 권장합니다. 이렇게 하면 사용 후 플레이어 인벤토리에서 제거되도록 양수 사용 횟수와 함께 정의할 수 있습니다.

서버 코드

클라이언트 코드

키와 컨테이너 소비

이전 예제에서는 키 및/또는 컨테이너를 소비 가능으로 설정하도록 제안했지만, 이는 권장사항일 뿐입니다. 그러나 컨테이너와 그 키(있는 경우)가 소비 불가능하다면, 컨테이너를 무한히 다시 열 수 있어 매번 그 내용물을 플레이어에게 부여할 수 있습니다. 플레이어 인벤토리 용량은 무한하지 않기 때문에, 이 패턴은 크게 권장되지 않습니다. 소비 가능한 컨테이너가 잠금 해제되면 컨테이너와 사용된 소비 가능한 키 모두 자동으로 사용 횟수가 감소하여, 사용 횟수가 0에 도달하면 플레이어 인벤토리에서 제거됩니다.

실행 가능한 옵션

소비 가능 컨테이너, 키 없음: 가장 기본적인 패턴으로, 컨테이너가 열릴 때 소비되며 키가 없습니다. 소비 가능 컨테이너, 소비 가능 키: 간단한 잠긴 컨테이너 사례로, 플레이어가 키로 컨테이너를 열 수 있습니다. 둘 다 소비되며, 플레이어는 사용 횟수가 남은 키로만 사용 횟수가 남은 컨테이너를 열 수 있습니다. 내구성 컨테이너, 소비 가능 키: 플레이어가 키를 찾을 때마다 컨테이너를 열 수 있습니다. 키는 소비되고, 컨테이너는 키에 사용 횟수가 남아 있는 동안에만 열립니다. 소비 가능 컨테이너, 내구성 키: 플레이어가 키 아이템이 되는 모든 컨테이너를 열 수 있는 키를 유지할 수 있게 해줍니다. 컨테이너는 소비되지만, 플레이어는 나중에 키로 컨테이너를 여는 능력을 유지합니다.

예제: 플레이어로부터 인벤토리 아이템 구매

프로세스가 게임별로 다르기 때문에 플레이어로부터 인벤토리 아이템을 다시 사는 내장 API가 없습니다. 그러나 기존 API 메서드를 사용하여 자신만의 SellItem 경험을 만들 수 있습니다:
  • PlayFab 서버 API RevokeInventoryItem** 은 인벤토리 아이템을 제거할 수 있게 해줍니다.
  • PlayFab 서버 API AddUserVirtualCurrency** 는 적절한 양의 가상 통화를 반환할 수 있습니다. 현재 PlayFab API 메서드를 통해 실제 화폐를 반환하는 것은 불가능합니다.
아이템과 가상 통화는 밀접한 관계가 있습니다. 자세한 내용은 Currencies 자습서를 참조하세요.
다음 CloudScript 함수는 앞에서 설명한 두 서버 호출을 단일 클라이언트 액세스 호출로 결합합니다.

모범 사례

  • 변경하기 전에 모든 클라이언트 입력 정보가 유효한지 확인하세요.
  • CloudScript는 원자적이지 않으므로 호출 순서가 중요합니다: AddUserVirtualCurrency는 성공하고 RevokeInventoryItem은 실패할 수 있습니다.
이 프로세스에서는 보상 없이 무언가를 빼앗는 것보다 플레이어에게 획득하지 않은 무언가를 주는 것이 일반적으로 더 좋습니다.
이 CloudScript 함수는 클라이언트에서 접근할 수 있습니다.
마지막 수정일 2026년 8월 25일