Posted on by

Today’s guest tutorial comes to you courtesy of Corona Ambassador and Portland, Oregon app developer Ed Maurina. Ed is a regular contributor to the weekly Corona Geek hangouts and an active member of the Corona Community. He has developed games for REEL FX Studios, maintains his Corona SSK game development library, and recently created a particle editor that runs in the Corona Simulator. Check out his work and blog at RoamingGamer.com.


For those who haven’t heard, Amazon recently released a new device called the Amazon Fire TV which goes head-to-head with Ouya, GameStick, Nvidia SHIELD, and others who want a piece of the Android console gaming action.

Recently, I released a small module (RGEasyFTV.lua) for capturing and emulating key inputs for the standard Fire TV controller/remote. This module captures the "onKey" event and then uses some coding tricks to generate a new event "onFTVKey". Additionally, when run in the Simulator, the module remaps specific OS X and Windows keys to the Fire TV key events, enabling development and testing in the Simulator.

In this tutorial, I will first show you how to write code that captures the new event "onFTVKey" and then does something with it. Next, I will discuss how you can integrate RGEasyFTV into an existing Composer app without changing the existing touch code. Both of these projects are available for download, so please obtain them before proceeding:

Fire TV = Easy as 1, 2, 3

If you want to start simple, or if you’re just curious to see this in action, you can test the justEvents project as follows:

1. Require the Module

require "RGEasyFTV"

2. Write an Event Listener

local function myListener( event )

    local keyName = event.keyName
    local phase = event.phase
    local time = system.getTimer()

    if ( event.phase == "began" ) then
        print( "Fire TV Key '" .. keyName .. "' pressed at time " .. time )
    elseif ( event.phase == "ended" ) then
        print( "Fire TV Key '" .. keyName .. "' released at time " .. time )
    end
    return true
end

3. Start Listening for Events

Runtime:addEventListener( "onFTVKey", myListener )

Now, you can simply run the app in the Simulator and, assuming you’re simulating an Android device, press the re-mapped keyboard keys (see Fire TV and Keyboard Mappings below).

Fire TV Inputs in an Existing Composer Project

Now, let’s talk about the (slightly) more difficult task of adding Fire TV inputs to an existing Composer project. However, before we start, I would like to assume the following:

  1. You have an existing Composer game/app.
  2. Your app has buttons to navigate from scene to scene.
  3. These buttons are mapped to functions which are included in the indivdual scene files.
  4. These functions can be called on their own.

Before Adding the Fire TV Input Code

The following code snippet is a valid Composer scene that draws a single button in the center of the screen. If that button is pressed, the scene will change to Scene 2.

local composer = require( "composer" )
local scene = composer.newScene()
local button = require "button"  --a super-minimal button builder

local function openScene2()
    local options = { effect = "fade", time = 200 }
    composer.gotoScene( "scene2", options )
end

function scene:create( event )
    local screenGroup = self.view
    button.new( screenGroup, 240, 160, 180, 40, "Scene 2", openScene2 )
end

scene:addEventListener( "create", scene )
return scene

For this example, I wrote a simple module called button.lua to do the work of drawing the button and handling touch inputs. The important thing to note is that this code will not be changed when we add the Fire TV input code in the next step.

After Adding the Fire TV Input Code

The following code is the same as the prior code with the addition of extra bits to tack on Fire TV input processing. Note the important numbered steps (commented).

local composer = require( "composer" )
local scene = composer.newScene()
local button = require "button"  --a super-minimal button builder

-- 1. Require The Fire TV Module
--
require "RGEasyFTV"

local function openScene2( )
    local options = { effect = "fade", time = 200, }
    composer.gotoScene( "scene2", options  )
end

-- 2. Set a flag to "ignore" Fire TV Inputs
--
local ignoreFTVInputs = true

-- 3. Write a listener that ignores Fire TV inputs if the flag is set
--    Otherwise, if the right (arrow) button is pressed, we call
--    "openScene2()" as if the on-screen button were pressed.
--
local function onFTVKey( event )
    if ( ignoreFTVInputs ) then return false end

    local keyName = event.keyName
    local phase = event.phase

    if ( phase ~= "ended" ) then return false end

    if ( keyName == "right" ) then
        openScene2()
        return true
    end

    return false
end

-- 4. Start listening for the "onFTVKey" event.
--
Runtime:addEventListener( "onFTVKey", onFTVKey )
function scene:create( event )
    local screenGroup = self.view
    button.new( screenGroup, 240, 160, 180, 40, "Scene 2", openScene2 )
end

-- 5. Add 'Composer' function to ignore or stop ignoring
--    Fire TV inputs at the right time.
--
function scene:show( event )
    local screenGroup = self.view
    local willDid = event.phase

    if ( willDid == "did" ) then
        ignoreFTVInputs = false
    end
end

function scene:hide( event )
    local screenGroup = self.view
    local willDid = event.phase

    if ( willDid == "will" ) then
        ignoreFTVInputs = true
    end
end

scene:addEventListener( "create", scene )

-- 6. Don't forget to register the two new Composer events.
--
scene:addEventListener( "show", scene )
scene:addEventListener( "hide", scene )
return scene

So, in summary, what are the main changes?

  1. We require the module "RGEasyFTV". This automatically starts listening for "onKey" events and re-maps them to Fire TV "onFTVKey" events.
  2. We add a local flag which can be set to true if we want to ignore "onFTVKey" events. I will explain more about this in a moment.
  3. We include a listener that, assuming the ignore flag is false, executes the openScene2() function whenever the “right” button is pressed.
  4. We then start listening for the "onFTVKey" event.
  5. We add two Composer event listeners to set or clear the ignore flag at the proper time.
  6. We start listening for these same events.

At the end of this short process, we have an app which still functions as a touch app but also responds to Fire TV inputs and the re-mapped keyboard inputs for testing.

The “ignoreFTVInputs” Flag

So, what was that bit with the ignore flag? Well, because we’re using a Runtime event listener to “catch” the "onFTVKey" event, we either need to stop listening when we leave the current scene, or we need to ignore the event when this scene is “offscreen.”

I find it easier and less prone to error to simply ignore inputs while the scene is hidden. Therefore, as you can see above, I added code to set the ignore flag to true as soon as the scene is exited. Similarly, it’s set to false as soon as the scene is entered.

If we didn’t handle this scenerio, our code would continue to catch events even when the scene was hidden. This would yield undefined behaviors in the best case.

Fire TV and Keyboard Mappings

Fire TV Input Keyboard Input Key Name
Up (ring top) up
Down (ring bottom) down
Left (ring left) left
Right (ring right) right
Select (ring center) s select
Back b back
Menu m menu
Rewind r mediaRewind
Fast Forward f mediaFastForward
Play/Pause p mediaPlayPause
Home (not catchable)
Microphone (not catchable)

In Summary

That’s about it! I hope you learned something while reading the above tutorial and that you feel confident enough to try porting your game or app to Fire TV.


Posted by . Thanks for reading...

5 Responses to “Tutorial: Amazon Fire TV – Controller Events”

  1. George

    Very cool! The Kindle Fire TV seems to be the best android console by a good margin at the moment.

    Any insight into how well games sell on it?

    Reply
  2. GP Animations

    I see a few sales a day from my Fire TV game app. I think what helps is it’s a very untapped market and when you buy a game controller, Amazon gives you $10 to spend on FTV apps. I think what hurts is there aren’t a ton of early adopters yet. That being said, from a consumer standpoint, I’m craving high-quality games that I can play with my game controller. Amazon is very eager to get games out on the platform, it only took them a few hours to approve my update this morning. I added game controller functionality to boost sales, so now people have the option of using their remote or bluetooth controller to play. I think there’s a lot of consumers like myself waiting for great FTV games to play like first-person shooters, side-scrollers, RPGs, etc.

    Reply

Leave a Reply

  • (Will Not Be Published)