Inicio rápido de Cocos2D-x

​

Configuración del proyecto de Cocos2d-x

1. Descargue e instale Cocos2d-x
   • https://www.cocos2d-x.org/download
   • Configurar Cocos2d-x requiere cierta familiaridad. Consulte su sitio de documentación:
     • https://docs.cocos2d-x.org/cocos2d-x/en/en/
     • Tenga en cuenta los requisitos previos de Cocos
     • También se requiere Visual Studio 2013 o 2015.
2. Una vez que tenga Cocos2d-x configurado, cree un proyecto con la CLI de Cocos:
   • Vaya a una ubicación donde desee almacenar su proyecto de Cocos
   • Abra una ventana de comandos en la carpeta primaria (la CLI de Cocos creará el directorio real del proyecto)
     • Mantenga presionada la tecla Mayús y haga clic con el botón derecho en el espacio en blanco vacío de la ventana del Explorador.
   • En la nueva ventana de consola, escriba este comando:
     • cocos new CocosGettingStarted -l cpp
       • Asegúrese de que el subdirectorio de destino (CocosGettingStarted) no exista ya; este comando fallará si la carpeta ya existe.
       • Si recibe un mensaje que indica que “‘cocos’ isn’t recognized as an internal or external command”, no ha configurado correctamente la instalación de cocos (vuelva a la guía de instalación de Cocos para Windows).
       • Si se realiza correctamente, habrá una carpeta nueva CocosGettingStarted. Esta guía se referirá a esa ubicación de directorio como {CocosGettingStarted}.
   • La salida correcta debería ser similar al ejemplo que se proporciona a continuación.

> 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'

3. Descargue el Cocos2d-xSdk de PlayFab: SDK de Cocos2D-x (C++). Guárdelo y extráigalo en una ubicación temporal {PlayFabCocos}
   • Abra la carpeta siguiente en el Explorador de Windows: {PlayFabCocos}/PlayFabClientSDK
   • Abra la carpeta siguiente en un segundo Explorador de Windows: {CocosGettingStarted}/Classes
4. Copie y pegue todos los archivos de {PlayFabCocos}/PlayFabClientSDK en {CocosGettingStarted}/Classes
5. En Visual Studio, cargue {CocosGettingStarted}/proj.win32/CocosGettingStarted.sln.
6. Queremos agregar los archivos de PlayFab al proyecto de Cocos.
7. En Visual Studio, en el panel del Explorador de soluciones, expanda hasta la carpeta: Solution/CocosGettingStarted/src
8. Abra una ventana del Explorador de Windows en {CocosGettingStarted}/Classes
   • Seleccione todos los archivos de {CocosGettingStarted}/Classes, EXCEPTO AppDelegate.h, AppDelegate.cpp, HelloWorldScene.h, HelloWorldScene.cpp
   • Arrastre y coloque todos esos archivos desde el Explorador a la carpeta Solution/CocosGettingStarted/src de Visual Studio que encontramos antes. Si experimenta problemas, puede arrastrar y colocar cada archivo de uno en uno, pero tenga cuidado de incluirlos todos.
   • Debería ver estos archivos en su proyecto de VS:

• Abra la ventana Properties de su proyecto CocosGettingStarted (como se muestra a continuación).
• Reemplace los directorios de inclusión adicionales por esto: $(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

​

Configurar la primera llamada API

1. En Visual Studio, dentro de la carpeta Solution/CocosGettingStarted/src, abra HelloWorldScene.h y reemplace el contenido por esto:
   • En Visual Studio, dentro de la carpeta Solution/CocosGettingStarted/src, abra HelloWorldScene.h y reemplace el contenido por el que se muestra a continuación.

#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__

2. Inmediatamente a continuación, abra HelloWorldScene.cpp y reemplace el contenido por esto:

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

​

Finalizar y ejecutar

1. Compile y ejecute su proyecto de Cocos: menús desplegables -> Debug -> Start Debugging.
2. Se le pedirá que compile. Seleccione Yes.
3. Debería ver una pantalla que dice: Congratulations, you made your first successful API call!
4. Ahora puede empezar a realizar otras llamadas API y a crear su juego.
   Para obtener una lista de todas las llamadas API de cliente disponibles, consulte nuestra documentación de referencias de API de PlayFab.

​

Análisis del código

• HelloWorldScene.h
  • Solo tiene modificaciones triviales respecto al HelloWorldScene.h predeterminado que genera Cocos.
  • En concreto, define parte de la interfaz gráfica de Cocos que estamos usando, y el prototipo de OnLoginSuccess y OnLoginFail.
  • Todo lo demás son funciones estándar del motor Cocos.
• HelloWorldScene.cpp
  • createScene() es una función estándar del motor Cocos.
  • init()
    • Elementos habituales de la interfaz gráfica de Cocos: closeItem y testReportLabel.
    • PlayFab::PlayFabSettings::titleId = "xxxx";
      • Cada desarrollador de PlayFab crea un título en Game Manager. Cuando publique su juego, debe codificar ese titleId en el juego. Esto permite al cliente saber cómo acceder a los datos correctos dentro de PlayFab. Para la mayoría de los usuarios, considérelo simplemente un paso obligatorio que hace que PlayFab funcione.
    • PlayFab::ClientModels::LoginWithCustomIDRequest request;
      • La mayoría de los métodos de la API de PlayFab requieren parámetros de entrada, y esos parámetros de entrada se empaquetan en un objeto de solicitud.
      • Cada método de la API requiere un objeto de solicitud único, con una combinación de parámetros opcionales y obligatorios.
        • En el caso de LoginWithCustomIDRequest, hay un parámetro obligatorio, CustomId, que identifica de forma única a un jugador, y CreateAccount, que permite crear una cuenta nueva con esta llamada.
      • Para el inicio de sesión, la mayoría de los desarrolladores querrán usar un método de inicio de sesión más apropiado.
        • Consulte la documentación de inicio de sesión de PlayFab para obtener una lista de todos los métodos de inicio de sesión y sus parámetros de entrada. Las opciones habituales son:
          • LoginWithAndroidDeviceID
          • LoginWithIOSDeviceID
          • LoginWithEmailAddress
    • PlayFab::PlayFabClientAPI::LoginWithCustomID(request, OnLoginSuccess, OnLoginFail, nullptr);
      • Esto inicia la solicitud asincrónica a LoginWithCustomID e invocará la función OnLoginSuccess o OnLoginFail cuando se complete.
  • update(float delta)
    • El simple hecho de establecer la variable statusMsg no actualiza el texto en pantalla.
    • Esta función establece el texto de la interfaz gráfica para que coincida con el contenido de statusMsg en cada tick (no muy eficiente).
  • OnLoginSuccess(result, customData)
    • Cuando se llama a la devolución de llamada de éxito, el objeto result de muchas devoluciones de llamada de la API contendrá la información solicitada.
    • LoginResult contiene información básica sobre el jugador pero, para la mayoría de los usuarios, el inicio de sesión es simplemente un paso obligatorio antes de llamar a otras API.
  • OnLoginFail(error, customData)
    • Si se llama a la función de error, la llamada API ha fallado.
    • Las llamadas API pueden fallar por muchos motivos, y siempre debe intentar controlar el error.
    • Por qué fallan las llamadas API (en orden de probabilidad)
      • PlayFabSettings.TitleId no está establecido. Si olvida establecer titleId en su título, nada funcionará.
        • En Cocos, la biblioteca curl probablemente bloqueará su juego si no establece titleId correctamente.
      • Parámetros de solicitud. Si no ha proporcionado la información correcta o requerida para una llamada API concreta, esta fallará. Consulte error.errorMessage, error.errorDetails o error.GenerateErrorReport() para obtener más información.
      • Problema de conectividad del dispositivo. Los teléfonos móviles pierden y recuperan la conectividad constantemente, por lo que cualquier llamada API en cualquier momento puede fallar aleatoriamente y funcionar inmediatamente después. Entrar en un túnel puede desconectarlo por completo.
      • Problema del servidor de PlayFab. Como con todo el software, puede haber problemas. Consulte nuestras notas de la versión para ver las actualizaciones.
      • Internet no es 100 % confiable. A veces, el mensaje se daña o no llega al servidor de PlayFab.
    • Si tiene dificultades para depurar un problema y la información incluida en la devolución de llamada de error no es suficiente, visítenos en nuestros foros.
  • customData es un puntero void, que puede usarse de cualquier manera para establecer contexto.
    • En C++, es más difícil mantener el contexto de una llamada API, por lo que agregamos el parámetro customData, que puede transmitir cualquier objeto a la devolución de llamada y usarse como desee para establecer contexto.
    • Así, si realiza llamadas API para recuperar el inventario, puede pasar un puntero de jugador o de inventario como customData y actualizar el inventario de ese objeto en la devolución de llamada.