We recently added support for the Ouya console platform for PRO users of GameBuilder Studio. It is a new android based gaming platform enabling us to build games for the living room. In this tutorial I will explain how you can utilize the new Ouya plugin and allow players to make in-app purchases to buy your game or purchase items in your game. Product information can be loaded from the Ouya servers as well as checking if a product was purchased already and trigger actions based on that. This plugin also handles on device storage and I will cover that in another tutorial.
The beauty of using GameBuilder Studio for Ouya game development is that there is no ODK or SDK needed to build and deploy your game over wifi to the Ouya console. It is really a seamless process. Build your game in GBs and then beam it to the device over your local wifi network. To detect your Ouya device on the local wifi network it needs to connect to your wifi device and ADB Network needs to be turned on in the system settings.
There are a number of preliminaries required before you can start to test in-app purchases. Ouya requires you to signup as a developer and submit a few tax related documents. I will walk you through this process.
Completing The Ouya Developer Info
Go to the products screen and fill out your developer profile, print and sign the W-9 tax document and add your payment information. You will want to do this asap because this information needs to be approved before you can add products to your Ouya developer account. Once you have filled out all of this information and it is approved, you will see the products entry screen.
Adding Products To Your OUYA Account
Unfortunately the Ouya API does not allow you to request a list of all available products so you will need to reference the product identifier directly. Fill out all the pricing information and make sure the product type is either Entitlement or Consumable. Subscriptions are not supported at this time. If you are creating a game that requires the player to purchase the full game before they have access to all the functionality in your game then just create an Entitlement product and you can select the product as the main purchasable item for the game when you create it later.
Setup The Ouya Game
Go to the game section of the site and click the create new game link. Fill out all of the default information and accept the terms. The package name must match whatever bundle Id you specify in the Ouya publish settings inside of GameBuilder Studio.
Download The Game Signing Key
Once the game is created go back to the Games screen to find the signing key (.der) that is needed to connect to the Ouya server in your game and download it. You can also now go to the main full game product for this game and link the game package id to the product. On the product edit screen there will be a new section called "Promoted Product For"
Initializing The Ouya Service
Once the game and products are created on the Ouya developer site you can start testing product purchases on the console. Create an entity with a Rules component. Add the "Ouya Initialization" action to the component. The initialization action requires the developer Id and the signing key that was downloaded earlier. Make sure to put quotes around the Developer id string. Import the signing key file (.der) and it will show up in the Private Key drop-down list. This action only needs to be run once but it needs to be run before any of the other Ouya actions can execute successfully.
Loading Product Information
Once you have initialized the ouya server connection then you can load product information about a particular product. The product id needs to be known ahead of time. Product information can be loaded and stored to a List Data component. You will need to know the properties available on the Product object for you to access them. When an entry is added to a List Data component it is just like an array in programming. However, in GameBuilder Studio the name of the property is as follows, itemX. Replace "X" with the index of the object's position in the list. This is a zero based index. The first entry in the List Data component will be item0, second will be item1, third is item2, etc. To access the product information stored to the LIst Data component you could use a property reference like this, @ListDataComponent.item0.name.
The available Product object properties are:
- identifier - a developer-facing identifier (unique per developer)
- name - the user-facing name
- description - the general description of the product
- currencyCode - defines the type of currency
- localPrice - the cost of the product given the type of currency
- originalPrice - the total price of the product given no sale is active
- percentOff - the percentage reduced from the original price
Purchase A Product
To purchase a product simply specify a product id and execute the Ouya Product action with the type set to "Purchase Product". Make sure the product id string surround by quotes so the expression engine knows it is a string. This will launch the purchase window asking the player for payment information. Once the player completes the purchase the on complete action will be triggered. Nothing will happen if they cancel the purchase.
Checking If The Product Has Been Purchased
Whenever the game is loaded check if a product has been purchased already. The action will only trigger the nested action if the product id specified has been purchased before and has a Receipt from the Ouya server. All previous purchase receipts can be loaded to a List Data component as well.
The Receipt object has the following properties:
- identifier - the product identifier
- currency - the currency that the product was purchased in
- localPrice - the cost of the product given the type of currency
- purchaseDate - when the purchase was made
- generatedDate - when the receipt was created
- gamer - the gamer that purchased the product
- uuid - the identifier of the gamer that purchased the product
Responding To The Ouya System Menu
Just listen for the system de-activated event in a Rules component to pause the game or save progress. This will be triggered whenever the Ouya system menu is opened.
Coding Purchases With the Ouya Plugin API
The Ouya plugin is based on an open-source native extension created by Gaslight Games. If you are a developer and you want to write the Ouya integration yourself it is possible. Any objects or plugins created in-editor can be accessed or changed via code. Below is an example of how to use the AS3 API.
The GameScreen class is auto generated when you run your game the first time from GBs. It is a top level class that can be used to overlay custom code into your game. The custom code base layer is now a PRO only feature. This AIROUYAFacadeANELib.swc file will also need to be included in whatever external IDE you choose to use for writing code if you want code hinting.
PRO users can download the Ouya plugin from the marketplace for free. Once you've downloaded the zip file copy the internal OuyaPlugin.swc file to the home folder's GameBuilderStudio -> plugins folder on your machine.