Cocos2D-x クイックスタート

[アーティクル]
07/11/2023

このクイックスタートは、Cocos2d-x エンジンで最初の PlayFab API の呼び出しを行うのに役立ちます。

PlayFab API を呼び出すには、PlayFab 開発者アカウントが必要です。

Cocos2d-x プロジェクトのセットアップ

OS: このガイドは、Visual Studio 2015 を使って Windows 10 用に記述されています。 Cocos はほとんどの最新 OS および環境で動作します。インストール手順は似ていますが、組み合わせごとに異なります。

他のプラットフォーム向けにビルドする場合、必要なファイルは同じですが、自分でプロジェクトセットアップが必要になります。 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 の Windows インストールガイドを確認してください)。
    - 成功した場合、新しいフォルダー 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} に展開します
- エクスプローラーでフォルダー {PlayFabCocos}/PlayFabClientSDK を開きます
- 2 番目のエクスプローラーでフォルダー {CocosGettingStarted}/Classes を開きます
{PlayFabCocos}/PlayFabClientSDK のすべてのファイルをコピーして {CocosGettingStarted}/Classes に貼り付けます
Visual Studio で、{CocosGettingStarted}/proj.win32/CocosGettingStarted.sln を読み込みます。
PlayFab ファイルを Cocos プロジェクトに追加します。
Visual Studio の [ソリューションエクスプローラー] パネルで、Solution/CocosGettingStarted/src フォルダーに展開します。
エクスプローラーで {CocosGettingStarted}/Classes を開きます
- AppDelegate.h、AppDelegate.cpp、HelloWorldScene.h、HelloWorldScene.cpp を除く、{CocosGettingStarted}/Classes のすべてのファイルを選択します
- エクスプローラーからすべてのファイルを、上記の Visual Studio ソリューションの CocosGettingStarted/src フォルダーにドラックアンドドロップします。問題が発生した場合、ファイルを 1 つずつドラッグアンドドロップできます。慎重にすべてのファイルを移動してください。
- VS プロジェクトに次のファイルが表示されます。

PlayFab では、依存関係の一覧に手動で追加する必要がある複数の Cocos ライブラリを使用します。

CocosGettingStarted プロジェクトの [プロパティ] ウィンドウを開きます (次を参照)。
追加のインクルードディレクトリを以下で置き換えます。

$(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();
}

これらのファイルは、新しい Cocos プロジェクトテンプレートの一部である既存の 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 開発者は、ゲームマネージャーでタイトルを作成します。ゲームを公開するとき、ゲームにそのタイトル ID をコードで記述する必要があります。これにより、クライアントは PlayFab 内で適切なデータにアクセスする方法を知ることができます。ほとんどのユーザーにとって、これは PlayFab が機能するための必須の手順です。
  - PlayFab::ClientModels::LoginWithCustomIDRequest request;
    - ほとんどの PlayFab API メソッドには入力パラメーターが必要であり、それらの入力パラメーターは要求オブジェクトにパックされています。
    - すべての API のメソッドには一意の要求オブジェクトが必要であり、オプションパラメーターおよび必須パラメーターが混在しています。
      - LoginWithCustomIDRequest の場合、プレイヤーを一意に識別する CustomId と、この呼び出しで新しいアカウントを作成できるようにする CreateAccount の必須パラメーターがあります。
    - ログイン時、ほとんどの開発者は適切なログイン方法を使うことを希望します。
      - すべてのログイン方法と入力パラメーターの一覧については、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)
  - エラー関数が呼び出された場合、API 呼び出しに失敗しました。
  - API 呼び出しは多くの理由で失敗するため、必ずエラーの処理を試みる必要があります。
  - API 呼び出しが失敗する理由 (可能性が高い順)
    - PlayFabSettings.TitleId は設定されていません。タイトルにタイトル ID を設定しなかった場合、何も機能しません。
      - 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 呼び出しのセットアップ

完成と実行

コードを分解する

その他のリソース