CS/INFO 4152: Advanced Topics in Computer Game Development

The Cornell-Cocos Engine

For years we let students use whatever engine they wanted for this course. It was a support nightmare. In addition, we had to make sure to break people up into Android-only groups, and iOS-only groups, which made team formation difficult. We desperately needed a cross-platform solution for this course. We also needed one in which it was relatively inexpensive to deploy to a mobile device (so not Unity). Our research turned up three viable options: LibGDX, Marmalade, and Cocos2D-X. Marmalade is too restrictive with its license, and LibGDX is very difficult to optimize on mobile devices.

We used Cocos2D-X for the first time last year. While it worked, there were a lot of growing pains because of bad design decisions in the Cocos engine. Therefore, we have made our own changes to the engine to this year to make it easier to use. In particular, we have made major changes to the physics interface and asset loading. We have improved the render to make wireframes more efficient. We have also greatly improved the sound engine on iOS.

download

Note: Download of this engine requires a valid Cornell net-id.


Getting Help

The engine is a slightly modified branch of Cocos2d-x 3.9. While it should be possible to merge the changes into the recently released 3.10, we did not have time to test this. In our opinion, the changes to 3.10 are not significant enough for this to matter. Either way, you can refer to the most recent Cocos API documentation in addition to our own documentation.

If you believe that you found a bug in our extensions, please let us know via Piazza. Your post should start with the word [BUG]. In addition, you should use the #bug tag.

For help beyond the API, such as setting up a new project, you should refer to the appropriate section for your development environment.

[Apple]     [Android]     [Windows]     [Linux]


Cornell-Cocos for Apple Devices

Currently, it is only possible to develop for iOS on a Macintosh. While Windows is pushing some cross-platform tools for iOS, they are neither compatible with Cocos nor our engine. However, you really only need one OS X machine on your team to deploy to a device. The cross-platform tools mean that everyone else on your team can develop and test on Windows using Visual Studio.

If no one on your team has access to a Macintosh, you can still develop for iOS. The CIS undergraduate computing lab in Gates G33 has several Macintoshes (because I specifically asked for them for this class). Most CS and INFO majors should already have access to this lab. If you need access to this lab and do not have it, please contact Jessica Depew.


Setting Up Your Computer

To develop for OS X and iOS, you must have XCode 7. XCode 6 or older is unacceptable. One reason for this is that it is much simpler to load on to a device in XCode 7. But more importantly, iOS 9 requires XCode 7. In general, every time you upgrade your version of iOS, you must upgrade your version of XCode.

Upgrading XCode may require that you upgrade to El Capitan if you have not already done so. We have upgraded our own machines and it appears to be safe. Do it now.


Creating a New Project

The way you create a new project in Cornell-Cocos is to copy an existing project and modify it to your purposes. Fortunately, Cocos has a command line utility to automate a lot of this for you. Download the engine above, and extract it to the folder cocos2d-cornell somewhere on your computer. Then follow the official instructions for a new project, substituting cocos2d-cornell for the folder cocos2d-x. The scripts setup.py and cocos should run the same.

The XCode project is located in the folder proj.ios_mac. It is one project file for both. Simply open it up.

Before you can compile, there is a very important step left out of the instructions. The XCode project will still have the old "Schemes". These are in the pull-down menu to the right of the Stop button. They are how you specify whether you want to compile for desktop or mobile. When you start up your new project, your schemes will be HelloCpp-mobile, and HelloCpp-desktop, carried over from the original template. However, as in the illustration below, these schemes will look like white gears, indicating that they are broken links.

old-schemes

You need to chose "Edit Schemes" and delete the first two schemes in the list above. Then you press the + button to add a new schema. There will be two options provided for you automatically: one for desktop and one for mobile. In the example below, we are constructing the schemes for the ShipDemo project. You will notice that the schemes now have the Pencil-and-Paintbrush icon indicating that it is ready to compile.

new-schemes


Loading on to a Device

Historically, Apple has locked down their devices so that only people with memberships in the iOS Developer Program could load on to a device. This is now changed with XCode 7. If you have XCode 7, your device is no longer locked and you can freely load software onto it from XCode.

However, there is one minor step you must do first. You must go into the mobile target, under the identity settings, and set your team to "personal". This is shown for the ShipDemo below. Plug in your device, select it under the schemes menu, and you are ready to go.

iostarget

Your device may ask you to verify some security settings before it launches. If you have any problems, please review the offical Apple instructions.

The XCode 7 solution is as good as anything that Cornell can provide you for free. However, if you want multiplayer support, then one member in your team will need to join the iOS Developer Program, which costs $100 per year. That is because networking requires iTunes Connect, which comes with the developer program and is only available to commercial (not academic) users. This program will also allow you to distribute your game commercially, so it is a good idea to have a membership if you want to develop your game beyond this course.


Cornell-Cocos for Android Devices

The preferred development environment for Android is Windows. That is because you cannot develop for Android in XCode, and Eclipse is not a good IDE for developing C++ applications. When you write C++ code, it should be in a professional IDE like XCode or Visual Studio. Hence we would like Android development to be done in Visual Studio.

This does not mean that everyone on the team needs to use Windows and Visual Studio. It is perfectly acceptable to have Macintosh developers on an Android-focused team. But development on a Mac should be in XCode and tested on either the desktop or an iOS device. Because of the cross-platform nature of the toys, this should be okay.


Setting Up Your Computer

First and foremost, you will need Visual Studio 2015. Only 2015 has support for Android projects, so anything older will not work. Unlike previous versions of Visual Studio, the Community version appears to have enough features to use for this class. However, remember that all Cornell students get access to Microsoft products via DreamSpark, so you could use that to get a more professional version. If you do not have a DreamSpark account, contact Jessica Depew about getting one.

To do any C++ Android development, you must also download the Android NDK. This is a separate suite of compilation tools, and both Visual Studio and Eclipse need it to deploy C++ code onto an Android device.


Creating a New Project

The way you create a new project in Cornell-Cocos is to copy an existing project and modify it to your purposes. Fortunately, Cocos has a command line utility to automate a lot of this for you. Download the engine above, and extract it to the folder cocos2d-cornell somewhere on your computer. Then follow the official instructions for a new project, substituting cocos2d-cornell for the folder cocos2d-x-3.1.1. The scripts setup.py and cocos should run the same.

The Visual Studio project is located in the folder proj.android. It should be called {YourProject}.sln. This solution links to two other projects, {YourProject}.AndroidNative and {YourProject}.AndroidPackaging, which represent the C++ project and Java wrapper project respectively. Make sure the AndroidPackaging project has a dependency on the AndroidNative project. You can check/edit this by launching Solution Properties from the Solution Explorer. You should also make sure the AndroidPackaging project is selected as the start-up project.

After verifying these dependencies, you should not need to edit any of the files again in either project, as they do not contain any meaningful source code. It will be convenient to add the individual projects from your proj.win32 solution for debugging purposes, but please remember to build the right project.


Loading on to a Device

To load onto an Android emulator, you should select the "x86" build configuration in Visual Studio and have an x86 Android system image ready. To load onto a standard Android phone, you should select the "ARM" build configuration.

Before you build, you may need to run the command

    android update project -p .

in the proj.android and cocos2d\cocos\platform\android\java directories on the command line (you can determine {target id} by running android list target and selecting an API - usually I use one of the non-Google ones). These generated files are specific to your machine, so you should not put these in your remote repository. If the android executable could not be found, you may run it from {Android SDK Path}\tools\android.bat.

Ideally, building and getting the app on your device should be as simple as connecting your device and selecting Start Debugging from within Visual Studio. However, what we believe to be a bug in Visual Studio currently prevents this one-click operation from actually deploying the app on your device. After successfully building the app, you will need to navigate to proj.android\{ARM|x86}\{Debug|Release}\{YourProject}.apk and manually install it onto your device. You should use the command

    adb install -r {YourProject}.apk

To debug an app, you should have it running on your device or emulator and use Debug > Attach to Android process. Your device must appear in the list shown when you execute the command adb devices. Look online to find out how to place your device in debugging mode if you are not sure how to do so.

It is possible that your build may fail with the error message "(...)AndroidNative.recipe could not be found". If that happens, you need to check your dependencies. This file is created when the AndroidNative project is built successfully, and is needed by the AndroidPackaging project.


Cornell-Cocos for Windows

Windows is not an intended target for this course. However, just as it is sometimes easier to test (and debug) an iOS build on the desktop first, you might find it easier to test your application on Windows in Visual Studio.

There is a possibility that the Windows builds will support Surface and Windows Phone. However, this is completely untested and we will not support this. The primary reason for the Windows build is to give you something to test without an Android device on hand.


Setting Up Your Computer

If you are working on Windows, you should use Visual Studio 2015. Only 2015 has support for Android projects, and there is no reason to have two different versions of Visual Studio on your computer. We recommend that you get a professional version and not use the community version. Remember that all Cornell students get access to Microsoft products via DreamSpark. If you do not have a DreamSpark account, contact Jessica Depew about getting one.


Creating a New Project

The way you create a new project in Cornell-Cocos is to copy an existing project and modify it to your purposes. Fortunately, Cocos has a command line utility to automate a lot of this for you. Download the engine above, and extract it to the folder cocos2d-cornell somewhere on your computer. Then follow the official instructions for a new project, substituting cocos2d-cornell for the folder cocos2d-x-3.1.1. The scripts setup.py and cocos should run the same.

The Visual Studio project is located in the folder proj.win32. Simply open it up. For the most part, all you have to do is add new files to this project. Make sure that the top-level project (not the Cocos2d-x project contained within) is selected as the start-up project.


Cornell-Cocos for Linux

While Cocos2d-x supports Linux builds, the Cornell extensions do not support them at this time. That is because Linux did not support the modern audio engine in 3.9 and we have not had time to test the Cornell extensions with 3.10 (and we would have to make some minor tweaks to that audio code anyway). If you absolutely have to get this running on Linux, please let us know on Piazza.