클라우드 도큐멘트 스토리지

개요

클라우드 도큐멘트 스토리지(Cloud Document Storage)는 일반적으로 게임 데이터를 저장하기 위해 "클라우드"에 보관되는 도큐멘트에(서) 데이터를 보관하(거나 읽어오)는 것을 말합니다.

주: 클라우드 도큐멘트 스토리지 함수성은, PC 에서 도큐멘트를 로컬에 저장하여 시뮬레이션되기는 해도, 현재 iOS 플랫폼에서 실행되는 게임에 제한되어 있습니다.

CloudStorageBase

CloudStorageBase 클래스는 클라우드 도큐멘트를 로드하고 저장하는 함수성이 담겨있는 베이스 클래스입니다. PlatformInterfaceBase 를 상속하여 그 클래스에 들어있는 델리게이트 시스템을 활용합니다. (PC, iOS 등) 각 플랫폼은 CloudStorageBase 에서 확장되는 자체 서브클래스가 있어, 해당 플랫폼 전용 구현을 제공합니다.

Functions 함수

• Init - 엔진이 클라우드 스토리지 시스템을 initialize 하기 위해 호출하는 이벤트입니다.
• ReadKeyValue [KeyName] [Type] [SerializedObj] - 클라우드 스토리지에서 키/값 쌍 읽기를 시작시키고, 성공하면 참을 반환합니다.
  • KeyName - 읽을 이름 (string) 입니다.
  • Type - 읽을 값의 EPlatformInterfaceDataType 종류입니다.
  • SerializedObj - 오브젝트를 읽는 경우, 바이너리 덩어리를 이 오브젝트로 de-serialize 합니다.
• WriteKeyValue [KeyName] [Value] - 클라우드에 키/값 쌍을 쓰고, 성공하면 참을 반환합니다.
  • KeyName - 쓸 키의 이름 (string) 입니다.
  • Value - 지정된 키에 쓸 PlatformInterfaceData 값입니다.
• QueryForCloudDocuments - 클라우드에 존재하는 도큐멘트 비동기 퀴리를 시작하고, 성공하면 참을 반환합니다. 이미 받아둔 도큐멘트가 있으면, 그 도큐멘트를 비우고 세트를 새로 고칩니다. 완료되면 GetNumCloudDocuments() 와 GetCloudDocumentName() 를 사용하여 기존 도큐멘트에 대한 정보를 구합니다.
• GetNumCloudDocuments [bIsForConflict] - QueryForCloudDocuments() 로의 콜 이후 클라우드에 존재하는 것으로 알려진 도큐멘트 수를 반환합니다.
  • bIsForConflict - 옵션. 참이면 도큐멘트 총 갯수 대신 충돌이 있는 도큐멘트 수가 반환됩니다.
• GetCloudDocumentName [Index] - 주어진 인덱스에 상응하는 도큐멘트 이름을 반환합니다.
  • Index - 이름을 구할 도큐멘트의 인덱스를 나타내는 Int 입니다.
• CreateCloudDocument [Filename] - 클라우드에 새 도큐멘트를 만듭니다. (initialize 도 안되어있고 저장도 안되어있으니 Write/Save 함수를 사용하세요.)
  • Filename - 새로 만든 도큐멘트에 줄 이름 (string) 입니다.
• ReadCloudDocument [Index] [bIsForconflict] - 도큐멘트를 메모리로 읽어옵니다. (또는 게임 지체 없이 ParseDocumentAs* 함수가 동기적으로 작동되게 하기 위해 필요한 작업을 해 줍니다.)
  • Index - 읽을 도큐멘트의 인덱스를 나타내는 Int 입니다.
  • bIsForConflict - 참이면 Index 는 모든 도큐멘트 배열이 아닌 충돌이 있는 도큐멘트 배열에 대한 인덱스가 됩니다.
• ParseDocumentAsString [Index] [bIsForConflict] - 전체 도큐멘트를 나타내는 문자열을 반환합니다. 도큐멘트를 읽을 때는 먼저 ReadCloudDocument() 를 사용해야 합니다. 이 함수는 SaveDocumentWithString() 를 사용하여 도큐멘트를 생성했을 때만 사용해야 합니다.
  • Index - 파싱할 도큐멘트의 인덱스를 나타내는 Int 입니다.
  • bIsForConflict - 참이면 Index 는 모든 도큐멘트 배열이 아닌 충돌이 있는 도큐멘트 배열에 대한 인덱스가 됩니다.
• ParseDocumentAsBytes [Index] [ByteData] [bIsForConflict] - 전체 도큐멘트를 나타내는 바이트 배열을 출력합니다. 도큐멘트를 읽을 때는 먼저 ReadCloudDocument() 를 사용해야 합니다. 이 함수는 SaveDocumentWithBytes() 를 사용하여 도큐멘트를 생성했을 때만 사용해야 합니다.
  • Index - 파싱할 도큐멘트의 인덱스를 나타내는 Int 입니다.
  • ByteData - 도큐멘트의 데이터로 채워진 바이트 배열입니다. 파싱이 실패하면 비어 있습니다.
  • bIsForConflict - 참이면 Index 는 모든 도큐멘트 배열이 아닌 충돌이 있는 도큐멘트 배열에 대한 인덱스가 됩니다.
• ParseDocumentAsObject [Index] [ObjectClass] [ExpectedVersion] [bIsForConflict] - 전체 도큐멘트를 나타내는 오브젝트를 반환합니다. 도큐멘트를 읽을 때는 먼저 ReadCloudDocument() 를 사용해야 합니다. 이 함수는 SaveDocumentWithObject() 를 사용하여 도큐멘트를 생성했을 때만 사용해야 합니다.
  • Index - 파싱할 도큐멘트의 인덱스를 나타내는 Int 입니다.
  • ObjectClass - 도큐멘트의 데이터를 사용하여 만들 오브젝트 Class 입니다.
  • ExpectedVersion - 데이터의 (SaveDocumentWithObject 를 통해 설정된) 예상 버전 번호를 나타내는 Int 입니다. 데이터 버전이 여기에 일치하지 않는다면 함수는 none 을 반환합니다.
  • bIsForConflict - 참이면 Index 는 모든 도큐멘트 배열이 아닌 충돌이 있는 도큐멘트 배열에 대한 인덱스가 됩니다.
• WriteCloudDocument [Index] - SaveDocumentWith* 함수를 사용하여 이미 "저장된" 도큐멘트를 씁니다.
  • Index - 쓸 도큐멘트의 인덱스를 나타내는 Int 입니다.
• SaveDocumentWithString [Index] [StringData] - 문자열을 입력 데이터로 하여 클라우드에 쓸 도큐멘트를 준비합니다. 동기성(synchronous)입니다.
  • Index - 저장할 도큐멘트의 인덱스를 나타내는 Int 입니다.
  • StringData - 파일에 저장할 String 데이터입니다.
• SaveDocumentWithBytes [Index] [ByteData] - 바이트 배열을 입력 데이터로 하여 클라우드에 쓸 도큐멘트를 준비합니다. 동기성(synchronous)입니다.
  • Index - 저장할 도큐멘트의 인덱스를 나타내는 Int 입니다.
  • ByteData - 파일에 저장할 바이트 배열입니다.
• SaveDocumentWithObject [Index] [ObjectData] [SaveVersion] - 오브젝트를 입력 데이터로 하여 클라우드에 쓸 도큐멘트를 준비합니다. 동기성(synchronous)입니다.
  • Index - 저장할 도큐멘트의 인덱스를 나타내는 Int 입니다.
  • ObjectData - 바이트로 serialize 하고 파일에 저장할 Object 데이터입니다.
  • SaveVersion - 저장할 오브젝트의 버전 번호를 나타내는 Int 입니다. 이 오브젝트를 로드할 때, 이 버전에 일치하지 않는 오브젝트는 로드하지 않습니다.
• ResolveConflictWithNewestDocument - 충돌 통지가 생기면, 클라우드 인터페이스더러 가장 최근에 수정된 버전을 선택하고, 다른 것은 던져 버리라고 이릅니다.
• ResolveConflictWithNewestVersionIndex [Index] - 충돌 통지가 생기면, 클라우드 인터페이스더러 주어진 인덱스 버전을 마스터 버전으로 선택하고, 다른 것은 던져 버리라고 이릅니다.
  • Index - 마스터 버전으로 유지할 도큐멘트 인덱스를 나타내는 Int 입니다.

Delegates 델리게이트

ECloudStorageDelegate enum 은 콜백을 받을 수 있는 델리게이트 종류에 대한 ID 를 정의합니다. 플랫폼 인터페이스 델리게이트 시스템을 사용하여 이들 각각에 델리게이트를 할당할 수 있습니다.

• CSD_KeyValueReadComplete - 이 ID 에 할당된 델리게이트는, ReadKeyValue() 를 통해 클라우드 키/값을 읽으려는 시도가 끝났을 때 실행됩니다.
  • bSuccessful - 값을 읽는 데 성공했으면 참입니다.
  • Data - 읽은 값입니다.
• CSD_KeyValueWriteComplete - 이 ID 에 할당된 델리게이트는, WriteKeyValue() 를 통해 클라우드 키/값을 쓰려는 시도가 끝났을 때 실행됩니다.
  • bSuccessful - 값을 쓰는 데 성공했으면 참입니다.
  • Data - 쓴 값입니다.
• CSD_ValueChanged - 이 ID 에 할당된 델리게이트는, 클라우드 키/값이 바뀔 때 실행됩니다.
  • bSuccessful - 성공하면 참입니다.
  • Data - 값이 변한 키 이름입니다.
• CSD_DocumentQueryComplete - 이 ID 에 할당된 델리게이트는, QueryCloudDocuments() 를 통해 클라우드 도큐멘트에 대한 퀴리가 끝났을 때 실행됩니다.
  • bSuccessful - 읽는 데 성공했으면 참입니다.
  • Data - 읽은 도큐멘트의 인덱스입니다.
• CSD_DocumentReadComplete - 이 ID 에 할당된 델리게이트는, ReadCloudDocument() 를 통해 읽을 도큐멘트를 열려는 시도가 끝났을 때 실행됩니다.
  • bSuccessful - 여는 데 성공했으면 참입니다.
  • Data - 연 도큐멘트의 인덱스입니다.
• CSD_DocumentWriteComplete - 이 ID 에 할당된 델리게이트는, WriteCloudDocument() 를 통해 도큐멘트를 쓰려는 시도가 끝났을 때 실행됩니다.
  • bSuccessful - 도큐멘트를 쓰는 데 성공했으면 참입니다.
  • Data - 쓴 도큐멘트의 인덱스입니다.
• CSD_DocumentConflictDetected - 이 ID 에 할당된 델리게이트는, 여러 기계에서 도큐멘트를 업데이트하여 충돌이 일어났을 때 실행됩니다. ResolveConflictWithNewest* 함수를 통해 스크립트가 사용할 버전을 결정하도록 하는 데 사용됩니다.
  • bSuccessful - 성공하면 참입니다.
  • Data - 충돌이 발생한 도큐멘트의 인덱스 입니다.

데이터로서의 Object

Object 와 그 프로퍼티를 serialize 시켜 클라우드 도큐멘트에 저장하면 클라우드 스토리지를 게임 데이터 저장용으로 활용할 수 있게 됩니다. 여기서 일반적인 개념은, 모든 데이터가 저장될 변수가 담긴, Object 에서 확장된 클래스가 생성된다는 것입니다. 이 게임 데이터 오브젝트의 인스턴스가 만들어지고 그 변수는 게임 도중 업데이트됩니다. 게임 저장 준비가 되면 이 오브젝트의 인스턴스가 SaveDocumentWithObject() 에 전달되고, 그 다음 도큐멘트가 WriteCloudDocument() 로 작성됩니다. 그리고서 게임 시작시 ReadCloudDocument() 와 ParseDocumentAsObject() 를 사용하여 데이터를 읽어들일 수 있는 것입니다.

구현 세부사항

언리얼 엔진 3 에서 클라우드 도큐멘트 스토리지를 셋업하여 사용하는 법에 대한 일반적인 작업방식은 개략적으로 아래와 같습니다:

1. 게임이 iOS 앱인 경우, iOS Provisioning Portal 에서 iCloud 서비스를 사용하도록 셋업되었는지 확인합니다. 자세한 정보는 Apple Developer Site 를 확인하시기 바랍니다.
2. PlatformInterfaceBase 클래스의 static GetCloudStorageInterface() 를 호출하여 CloudStorageBase 오브젝트로의 리퍼런스를 구한 다음 처리하려는 (도큐멘트 퀴리, 값 변경/읽기/쓰기, 도큐멘트 읽기/쓰기, 충돌 감지 등의) 델리게이트를 셋업해 줍니다. 이들은 보통 PostBeginPlay() 에 있거나, 클라우드 도큐멘트 함수성을 놓은 곳에 따라 다른 초기화(initialization) 함수에 있을 수도 있습니다.

   var CloudStorageBase Cloud;

   ...

   Cloud = class'PlatformInterfaceBase'.static.GetCloudStorageInterface();
   Cloud.AddDelegate(CSD_ValueChanged, CloudValueChanged);
   Cloud.AddDelegate(CSD_DocumentReadComplete, CloudReadDocument);
   Cloud.AddDelegate(CSD_DocumentConflictDetected, CloudConflictDetected);

   delegate PlatformInterfaceDelegate(const out PlatformInterfaceDelegateResult Result);

1. 게임에서 쓸 도큐먼트 목록을 구하려면, CloudStorageBase 오브젝트에서 QueryForCloudDocuments() 를 호출하고, 원하는(, 보통 메뉴같은) 방식으로 사용자에게 도큐멘트 목록을 표시하는 작업을 처리하는 곳인 CSD_DocumentQueryComplete 콜백을 기다립니다.

   Cloud.QueryForCloudDocuments();

1. 도큐멘트를 읽으려면 ReadCloudDocument() 를 호출한 다음 예상되는 데이터 형태에 따라 ParseDocumentAs*() 함수 중 하나를 사용합니다.

   Cloud.ReadCloudDocument(0);
   StringData = Cloud.ParseDocumentAsString(0);

1. 도큐멘트를 저장하려면, SaveDocumentAs*() 함수 중 하나에 적절한 데이터를 전달해서 호출하고, WriteCloudDocument() 를 호출하여 도큐멘트를 저장합니다.

   Cloud.SaveDocumentAsString(0, StringData);
   Cloud.WriteCloudDocument(0);