Getting Started with OUYA (2014)
Chapter 4. Guidelines for Setting Up the OUYA ODK
This chapter will explain the various resources, folders, and libraries in the ODK, and the code that needs to be created to initiate a project for the OUYA console.
Starting with the OUYA Development Kit
The OUYA Development Kit (OUYA ODK) is a tool to create games and applications for the OUYA console, and its extensions and libraries are in the .jar format. It is released under Apache License Version 2.0.
The OUYA ODK contains the following folders:
· Licenses: The SDK games and applications depend on various open source libraries. This folder contains all the necessary authorizations for the successful compilation and publication of the project in the OUYA console or testing in the emulator.
· Samples: This folder has some scene examples, which help to show users how to use the Standard Development Kit.
· Javadoc: This folder contains the documentation of Java classes, methods, and libraries.
· Libs: This folder contains the .jar files for the OUYA Java classes and their dependencies for the development of applications for the OUYA console.
· OUYA Framework APK file: This file contains the core of the OUYA software environment that allows visualization of a project based on the environment of OUYA.
· OUYA Launcher APK file: This file contains the OUYA launcher that displays the generated .apk file.
The ODK plugin within Unity3D
Download the Unity3D plugin for OUYA. In the developer portal, you will find these resources at https://github.com/ouya/ouya-unity-plugin.
After downloading the ODK plugin, unzip the file in the desktop and import the ODK plugin for the Unity3D folder in the interface engine of the Assets folder; you will find several folders in it, including the following ones:
· Ouya: This folder contains the Examples, SDK, and StarterKit folders
· LitJson: This folder contains libraries that are important for compilation
· Plugins: This folder contains the Android folder, which is required for mobile projects
"The Last Maya" created with the .ngui extension
Importing the ODK plugin within Unity3D
The OUYA Unity plugin can be imported into the Unity IDE. Navigate to Assets | Import Package | Custom Package…. Find the Ouya Unity Plugin folder on the desktop and import all the files. The package is divided into Core and Examples. The Core folder contains the OUYA panel and all the code for the construction of a project for the console. The Core and Examples folders can be used as individual packages and exported from the menu, as shown in the following screenshot:
A complete documentation on the ODK plugin for Unity3D can be found at https://devs.ouya.tv/developers/docs/unity.
Installing and configuring the ODK plugin
First, execute the Unity3D application and navigate to File | Open Project and then select the folder where you need to put the OUYA Unity plugin.
You can check if Ouya Unity Plugin has been successfully imported by having a look at the window menu at the top of Unity3D, where the toolbars are located. In this manner, you can review the various components of the OUYA panel.
While loading the OUYA panel, a window will be displayed with the following sections and buttons:
· Build Application: This is the first button and is used to compile, build, and create an Android Application Package file (APK)
· Build and Run Application: This is the next button and allows you to compile the application, generate an APK, and then run it on the emulator or publish directly to a device connected to the computer
· Compile: This button compiles the entire solution
The lower section displays the paths of different libraries. Before it uses the OUYA plugin, the user ought to edit the fields in the PlayerSettings window (specifically the Bundle Identifier field), set the Minimum API Level field to API level 16, and set the Default Orientation field to Landscape Left. Another button that is mandatory is Bundle Identifier synchronizer, which synchronizes the Android manifest file (XML) and the identifiers of Java packages.
Remember that the package ID must be unique for each game and has to be edited to avoid synchronization problems.
Also, the OuyaGameObject (shown in the following screenshot) is very important for use in in-app purchases:
The OUYA panel
The Unity tab in the OUYA panel shows the path of the Unity JAR file, which houses the file's JAR class. This file is important because it is the one that communicates with the Unity Web Player. This Unity tab is shown in the following screenshot:
The Java JDK tab shows the routes of the Java Runtime installation with all its different components to properly compile a project for Android and OUYA, as shown in the following screenshot:
The Android SDK tab displays the current version of the SDK and contains the paths of the different components of the SDK: Android Jar Path ADB, APT SDK Path, and Path, as shown in the following screenshot. These paths must correspond to the PATHenvironment variable of the operating system.
Finally, the last tab of the OUYA panel, Android NDK, shows the installation path of C++ scripts for native builds, as shown in the following screenshot:
Installing and configuring the Java class
If at this point you want to perform native development using the NDK or have problems opening or compiling the OUYA project, you need to configure the Java files.
To install and configure the Java class, perform the following steps:
1. Download and install the JDK 1.6 and configure the Java Runtime path in the PATH environment variable.
2. Next, you need to set a unique bundle, identifier.com.yourcompany.gametitle.
3. Hit the Sync button so your packages and manifest match.
4. Create a game in the developer portal that uses the bundle ID. Download that signing key (key.der) and save it in Unity.
5. Compile the Java plugin and the Java application.
6. Input your developer UUID from the developer portal into the OuyaGameObject in the scene.
Identifying the user
Every developer who wants to create an application for OUYA needs a unique identification number, called the UUID code. It allows access to the application development API and real-time purchasing system on the console. In any OUYA project, include this number in the source code to be properly identified in the OUYA marketplace and prevent fraud.
You can find your UUID code on the main page of the OUYA developer portal (https://devs.ouya.tv/developers) after you log in.
The UUID code has a structure similar to the following one:
An example UUID code is shown in the following screenshot:
Once you have a developer ID, you must include it within the OuyaSDK.cs and ouyaInputHandler.cs scripts as shown in the following screenshot. This will allow you to access the purchasing system on the console.
UUID code (OuyaInputHandler)
Starter kit – examples
The ODK plugin for Unity3D contains the following four scenes:
· Initial scene
· Welcome scene
· Main menu scene
· Game scene
The preceding scenes are shown in the following screenshot:
The Unity/OUYA Starter kit
You will find the following three main files inside the Scenes folder:
· SceneInit.Unity: This is the application file that runs at the beginning
· SceneSplash.Unity: This is the scene showing the title or cover of the game
· SceneMain.Unity: This is the main game scene
The initial scene contains the OuyaGameObject script. This script allows the welcome scene to load.
The main scene is associated with a GUI button that allows the game to load.
Common errors while working with OUYA
In the next section, we'll be covering some errors that are commonly encountered while working on the OUYA system.
Errors with the emulator
The configuration of the emulator with an optimal resolution is one of the greatest hurdles to overcome before we can begin testing with our APK.
One of the first steps to avoid errors is to correctly configure the paths for the Android SDK and the Java Runtime, and include them in the PATH environment variable of your operating system.
Additionally, you need to install the Intel x86 Atom System package within the Android SDK.
Install Intel x86 Atom System package
It is important to remember that the use of a non-Intel processor for the various tests can affect emulator screen resolutions and configuration processes. This virtualization of Android hardware makes the emulator run much faster, but it is only available to you if you have an Intel CPU.
Errors with Eclipse
If you use the Eclipse IDE, a typical error is generated during Java configuration. To resolve this problem, install the 32-bit version of the Java Runtime.
Errors with the ADB connection USB
There should be no carriage return after the hex value. Any blank lines in this file will result in an error. Add ~/ to android/adb_usb.ini.
Create the adb_usb.ini file if it doesn't exist so your OUYA console can be recognized, and then insert the following command:
Errors in the OUYA panel
When opening the OUYA panel window, you may receive the Mismatched Bundle Error. It appears because of issues in the synchronization of paths.
To correct this error, click on the Sync Bundle ID button. The error will disappear after a few seconds.
Other errors may occur when compiling Android from Unity. To correct this, you can download the 32-bit version of the Java Runtime at the following link (this alternative procedure can only be used in the Windows platform):
In this chapter, we explained the most important ODK plugin settings for Unity3D as well as the importance of using the UUID identification code developed for the OUYA project. Integrating the UUID code with your code in order to implement in-game purchases will be covered later in the book.
We also identified the most common mistakes when working on the development environment for OUYA.
In the next chapter, we will elaborate on the project: configuration of controllers, compilation, and execution of the video game.