Cocos2D x 빠른 시작

아티클
07/13/2023

이 빠른 시작은 Cocos2d-x 엔진에서 첫 번째 PlayFab API 호출을 만드는 데 도움이 됩니다.

PlayFab API를 호출하려면 먼저 PlayFab 개발자 계정이 있어야 합니다.

Cocos2d-x 프로젝트 설정

OS: 이 가이드는 Visual Studio 2015를 사용하는 Windows 10용으로 작성되었습니다. Cocos는 현재 대부분의 운영 체제 및 환경에서 작동합니다. 설치 지침은 비슷하지만 각 조합에 따라 다릅니다.

다른 플랫폼용으로 빌드하는 경우 필요한 파일은 동일하지만 사용자가 직접 프로젝트를 설정해야 합니다. Visual Studio 2013에서도 동일한 단계를 수행하지만 여기에 제공된 스크린샷은 약간 다를 수 있습니다.

Cocos2d-x 다운로드 및 설치
- https://www.cocos2d-x.org/download
- Cocos2d-x를 설정하려면 어느 정도 익숙해져야 합니다. 해당 문서 사이트를 확인하세요.
  - https://docs.cocos2d-x.org/cocos2d-x/en/en/
  - Cocos 사전 요건을 참조하세요.
  - Visual Studio 2013 또는 2015도 필요합니다.
Cocos2d-x가 구성되어 있으면 Cocos CLI를 사용하여 프로젝트를 만듭니다.
- Cocos 프로젝트를 저장할 위치로 이동합니다.
- 상위 폴더에서 명령 창을 엽니다(Cocos CLI가 실제 프로젝트 디렉터리를 만듭니다).
  - Shift 키를 누른 채 탐색기 창의 빈 공간을 마우스 오른쪽 단추로 클릭합니다.
- 새 콘솔 창에서 다음 명령을 입력합니다.
  - cocos new CocosGettingStarted -l cpp
    - 대상 하위 디렉터리(CocosGettingStarted)가 아직 존재하지 않는지 확인합니다. 폴더가 이미 있는 경우 이 명령은 실패합니다.
    - "'cocos'가 내부 또는 외부 명령으로 인식되지 않았습니다"라는 메시지가 표시되는 경우에는 cocos 설치가 제대로 구성되지 않은 것입니다(Cocos 창 설치 가이드로 돌아가십시오).
    - 성공했다면 새 폴더 CocosGettingStarted가 표시됩니다. 이 가이드에서는 해당 디렉터리 위치를 {CocosGettingStarted}로 참조합니다.
- 성공적인 출력은 아래에 제공된 예제와 유사하게 표시됩니다.

> Copy template into C:\dev\CocosGettingStarted
> Copying Cocos2d-x files...
> Rename project name from 'HelloCpp' to 'CocosGettingStarted'
> Replace the project name from 'HelloCpp' to 'CocosGettingStarted'
> Replace the project package name from 'org.cocos2dx.hellocpp' to 'org.cocos2dx.CocosGettingStarted'
> Replace the Mac bundle id from 'org.cocos2dx.hellocpp' to 'org.cocos2dx.CocosGettingStarted'
> Replace the iOS bundle id from 'org.cocos2dx.hellocpp' to 'org.cocos2dx.CocosGettingStarted'

PlayFab Cocos2d-xSdk: Cocos2D-x SDK (C++)를 다운로드합니다. 임시 위치 {PlayFabCocos}에 저장하고 압축을 풉니다.
- Windows 탐색기에서 {PlayFabCocos}/PlayFabClientSDK 폴더를 엽니다.
- 두 번째 Windows 탐색기에서 {CocosGettingStarted}/Classes 폴더를 엽니다.
{PlayFabCocos}/PlayFabClientSDK에서 {CocosGettingStarted}/Classes로 모든 파일을 복사하여 붙여넣습니다.
Visual Studio에서 {CocosGettingStarted}/proj.win32/CocosGettingStarted.sln을(를) 로드합니다.
이제 PlayFab 파일을 Cocos 프로젝트에 추가하려고 합니다.
Visual Studio의 솔루션 탐색기 패널에서 Solution/CocosGettingStarted/src 폴더로 확장합니다.
{CocosGettingStarted}/Classes에서 Windows 탐색기 창을 엽니다.
- {CocosGettingStarted}/Classes에서 AppDelegate.h, AppDelegate.cpp, HelloWorldScene.h, HelloWorldScene.cpp를 제외한 모든 파일을 선택합니다.
- 탐색기에서 이 모든 파일을 앞서 찾은 Visual Studio 솔루션 CocosGettingStarted/src 폴더에 끌어 놓습니다. 문제가 발생하는 경우 각 파일을 한 번에 하나씩 끌어서 놓을 수 있습니다. 모든 파일을 옮기도록 주의하십시오.
- VS 프로젝트에 다음 파일이 표시됩니다.

PlayFab에서는 수동으로 종속성 목록에 추가해야 하는 여러 개의 Cocos 라이브러리를 사용합니다.

다음 그림과 같이 CocosGettingStarted 프로젝트에 대한 속성 창을 엽니다.
Additional Include Directories를 다음과 같이 바꿉니다.

$(ProjectDir)..\cocos2d\external\zlib\include;$(ProjectDir)..\cocos2d\external\curl\include\win32;$(EngineRoot)cocos\audio\include;$(EngineRoot)external;$(EngineRoot)external\chipmunk\include\chipmunk;$(EngineRoot)extensions;..\Classes;..;%(AdditionalIncludeDirectories);$(_COCOS_HEADER_WIN32_BEGIN);$(_COCOS_HEADER_WIN32_END);..\cocos2d

참고 항목

여기서는 Cocos와 함께 제공된 curl 및 zlib를 추가하지만 기본적으로 활성화되지 않습니다.

이제 CocosGettingStarted 프로젝트가 컴파일 및 실행되어야 하지만, 아직 PlayFab API 호출을 수행하지 않습니다.

설치가 완료되었습니다!

첫 번째 API 호출 설정

이 가이드는 첫 번째 PlayFab API 호출을 만들기 위한 최소한의 단계를 제공합니다. 앱에 확인이 표시됩니다.

Visual Studio의 Solution/CocosGettingStarted/src 폴더에서 HelloWorldScene.h를 열고 내용을 다음과 같이 바꿉니다.
- Visual Studio의 Solution/CocosGettingStarted/src 폴더에서 HelloWorldScene.h 를 열고 콘텐츠를 아래 표시된 내용으로 교체합니다.

#ifndef __HELLOWORLD_SCENE_H__
#define __HELLOWORLD_SCENE_H__

#include "cocos2d.h"
#include "PlayFabClientDataModels.h"
#include "PlayFabError.h"

class HelloWorld : public cocos2d::Layer
{
public:
    static std::string statusMsg;
    static cocos2d::Scene* createScene();
    static cocos2d::Label* testReportLabel;
    virtual bool init();
    void update(float) override;
    void menuCloseCallback(cocos2d::Ref* pSender);
    CREATE_FUNC(HelloWorld);

    static void HelloWorld::OnLoginSuccess(const PlayFab::ClientModels::LoginResult& result, void* customData);
    static void HelloWorld::OnLoginFail(const PlayFab::PlayFabError& error, void* customData);
};

#endif // __HELLOWORLD_SCENE_H__

바로 옆에 있는 HelloWorldScene.cpp을(를) 열고 내용을 다음과 같이 바꿉니다.

#include "HelloWorldScene.h"
#include "PlayFabClientAPI.h"
#include <PlayFabSettings.h>

USING_NS_CC;

std::string HelloWorld::statusMsg;
cocos2d::Label* HelloWorld::testReportLabel;

Scene* HelloWorld::createScene()
{
    auto scene = Scene::create(); // 'scene' is an autorelease object
    auto layer = HelloWorld::create(); // 'layer' is an autorelease object
    scene->addChild(layer); // add layer as a child to scene
    return scene; // return the scene
}

bool HelloWorld::init()
{
    if (!Layer::init())
        return false;

    Size visibleSize = Director::getInstance()->getVisibleSize();
    Vec2 origin = Director::getInstance()->getVisibleOrigin();

    auto closeItem = MenuItemImage::create("CloseNormal.png", "CloseSelected.png", CC_CALLBACK_1(HelloWorld::menuCloseCallback, this));
    closeItem->setPosition(Vec2(origin.x + visibleSize.width - closeItem->getContentSize().width / 2, origin.y + closeItem->getContentSize().height / 2));

    auto menu = Menu::create(closeItem, NULL);
    menu->setPosition(Vec2::ZERO);
    this->addChild(menu, 1);
    this->scheduleUpdate();

    testReportLabel = Label::createWithTTF("", "fonts/Marker Felt.ttf", 14);
    this->addChild(testReportLabel, 1);

    statusMsg = "Login pending...";
    PlayFab::PlayFabSettings::titleId = "144";
    PlayFab::ClientModels::LoginWithCustomIDRequest request;
    request.CustomId = "GettingStartedGuide";
    request.CreateAccount = true;
    PlayFab::PlayFabClientAPI::LoginWithCustomID(request, OnLoginSuccess, OnLoginFail, nullptr);

    return true;
}

void HelloWorld::menuCloseCallback(Ref* pSender)
{
    Director::getInstance()->end();
#if (CC_TARGET_PLATFORM == CC_PLATFORM_IOS)
    exit(0);
#endif
}

void HelloWorld::update(float delta)
{
    Size visibleSize = Director::getInstance()->getVisibleSize();
    Vec2 origin = Director::getInstance()->getVisibleOrigin();

    testReportLabel->setPosition(Vec2(origin.x + visibleSize.width / 2, origin.y + visibleSize.height / 2));
    testReportLabel->setString(statusMsg);
}

void HelloWorld::OnLoginSuccess(const PlayFab::ClientModels::LoginResult& result, void* customData)
{
    statusMsg = "Congratulations, you made your first successful API call!";
}


void HelloWorld::OnLoginFail(const PlayFab::PlayFabError& error, void* customData)
{
    statusMsg = "Something went wrong with your first API call.\n";
    statusMsg += "Here's some debug information:\n";
    statusMsg += error.GenerateErrorReport();
}

이러한 파일은 new-Cocos-project 템플릿의 일부인 기존 HelloWorldScene을 취하며, 이를 첫 번째 PlayFab API 호출을 포함하도록 수정합니다.

완료 및 실행

Cocos 프로젝트 빌드 및 실행: 드롭다운 -> 디버그 -> 디버깅 시작
이 경우 빌드를 요청하는 메시지가 표시될 수 있습니다. 예를 선택합니다.
다음과 같은 화면이 표시됩니다.

축하합니다. 첫 번째 API 호출을 성공적으로 만들었습니다.
이제 다른 API 호출을 만들고 게임 빌드를 시작할 수 있습니다.
사용 가능한 모든 클라이언트 API 호출 목록을 보려면 PlayFab API 참조 설명서를 참조하세요.

즐거운 코딩이 되시길 바랍니다.

코드 분해

선택 사항인 이 마지막 섹션은 앞의 소스 코드의 각 부분을 자세히 설명합니다.

HelloWorldScene.h
- 이는 Cocos에 의해 생성된 기본 HelloWorldScene.h에서 약간만 수정된 것입니다.
- 특히, 사용 중인 일부 Cocos GUI와 OnLoginSuccess 및 OnLoginFail의 프로토타입을 정의합니다.
- 다른 모든 항목은 표준 Cocos 엔진 기능일 뿐입니다.
HelloWorldScene.cpp
- createScene()은(는) 표준 Cocos 엔진 기능입니다.
- init()
  - 일반적인 Cocos Gui 항목은 closeItem 및 testReportLabel입니다.
  - PlayFab::PlayFabSettings::titleId = "xxxx";
    - 모든 PlayFab 개발자가 게임 관리자에서 타이들을 만듭니다. 게임을 게시할 때 게임에 해당 titleId를 코딩해야 합니다. 이렇게 하면 클라이언트가 PlayFab 내에서 올바른 데이터에 액세스하는 방법을 알 수 있습니다. 대부분의 사용자는 이 작업을 PlayFab을 작동시키기 위한 필수 단계로 생각하면 됩니다.
  - PlayFab::ClientModels::LoginWithCustomIDRequest request;
    - 대부분의 PlayFab API 메서드에는 입력 매개 변수가 필요하고 이러한 입력 매개 변수는 요청 개체로 압축됩니다.
    - 모든 API 메서드는 선택적 매개 변수와 필수 매개 변수가 혼합된 고유 요청 개체가 필요합니다.
      - LoginWithCustomIDRequest의 경우, 플레이어와 CreateAccount를 고유하게 식별하는 CustomId라는 필수 매개 변수가 있어 이 호출로 새로운 계정을 생성하도록 합니다.
    - 로그인을 위해 대부분의 개발자들은 보다 적절한 로그인 메서드를 사용하고자 합니다.
      - 모든 로그인 메서드 및 입력 매개 변수 목록 목록은 PlayFab 로그인 설명서를 참조하세요. 일반적인 옵션은 다음과 같습니다.
        
        LoginWithAndroidDeviceID
        
        LoginWithIOSDeviceID
        
        LoginWithEmailAddress
  - PlayFab::PlayFabClientAPI::LoginWithCustomID(request, OnLoginSuccess, OnLoginFail, nullptr);
    - 이는 LoginWithCustomID에 대한 비동기 요청이 시작되고 완료 시 OnLoginSuccess 또는 OnLoginFail 함수가 호출됩니다.
- update(float delta)
  - 단순히 statusMsg 변수를 설정하면 화면 텍스트가 업데이트되지는 않습니다.
  - 이 함수는 statusMsg의 모든 내용과 일치하도록 GUI 텍스트를 설정합니다(매우 효율적이지 않음).
- OnLoginSuccess(result, customData)
  - 성공 콜백이 호출되면, 많은 API 콜백에 대한 결과 개체에 요청된 정보가 포함됩니다.
  - LoginResult는 플레이어에 대한 몇 가지 기본 정보를 포함하지만 대부분의 사용자에게 로그인은 다른 API를 호출하기 전에 수행해야 할 필수 단계일 뿐입니다.
- OnLoginFail(error, customData)
  - error-function이 호출되면 API 호출이 실패한 것입니다.
  - API 호출은 여러 가지 이유로 실패할 수 있으며, 항상 실패 처리를 시도해야 합니다.
  - API 호출이 실패하는 이유(가능성이 높은 순서대로 나열)
    - PlayFabSettings.TitleId이(가) 설정되지 않았습니다. 타이틀에 대한 titleId를 설정하는 것을 잊은 경우, 아무 것도 작동하지 않습니다.
      - Cocos에서는 titleId를 올바르게 설정하지 않은 경우 curl 라이브러리가 게임을 중단할 수 있습니다.
    - 요청 매개 변수. 특정 API 호출에 대해 정확하거나 필요한 정보를 제공하지 않은 경우 호출에 실패합니다. 자세한 내용은 error.errorMessage, error.errorDetails 또는 error.GenerateErrorReport()를 참조하세요.
    - 장치 연결 문제. 휴대폰은 지속적으로 연결이 끊어졌다가 다시 연결되므로 언제든지 모든 API 호출이 실패하고 난 후 바로 다시 작동할 수 있습니다. 터널로 들어가면 연결이 완전히 끊길 수 있습니다.
    - PlayFab 서버 문제. 모든 소프트웨어와 마찬가지로 문제가 있을 수 있습니다. 업데이트에 대해서는 릴리스 정보를 참조하세요.
    - 인터넷은 100% 신뢰할 수 없습니다. 때때로 메시지가 손상되었거나 PlayFab 서버에 연결되지 않을 수 있습니다.
  - 문제를 디버깅하는 데 문제가 있는 경우 오류 콜백 내의 정보로는 충분하지 않습니다. 포럼에서 문의해 주세요.
- customData는 컨텍스트를 설정하기 위해 모든 방식으로 사용할 수 있는 void 포인터입니다.
  - C++에서 API 호출의 컨텍스트를 유지하는 것은 더 어려운 일이므로 모든 개체를 콜백에 릴레이할 수 있는 customData 매개 변수를 추가했으므로 컨텍스트를 설정하기 위해 마음대로 사용할 수 있습니다.
  - 따라서 API를 호출하여 인벤토리를 검색하는 경우 콜백에서 플레이어를 전달하거나, 포인터를 customData 인벤토리로 만들거나, 해당 개체의 인벤토리를 업데이트할 수 있습니다.

다음을 통해 공유

Cocos2D x 빠른 시작

Cocos2d-x 프로젝트 설정

첫 번째 API 호출 설정

완료 및 실행

코드 분해

피드백

추가 리소스