Tutorial: Amazon Fire TV – Controller Events

Share on Facebook0Share on Google+1Tweet about this on TwitterShare on LinkedIn1

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

2. Write an Event Listener

3. Start Listening for Events

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.

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).

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.

Share on Facebook0Share on Google+1Tweet about this on TwitterShare on LinkedIn1

Brent Sorrentino serves as a full-time Developer Evangelist for Corona Labs, assisting developers in the forums, maintaining documentation/guides, and creating samples which highlight core features of Corona SDK.

This entry has 8 replies

  1. Well AWESOME – i have been lusting over the Amazon TV for a while. Now I have a reason to buy one ASAP.. Thanks so much.

  2. Thank you for sharing this Ed 🙂

  3. George says:

    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?

  4. 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.

  5. Rob says:

    I have added this to the RGEasyTV module in the FTV codes section so the joypad works. I routed the A and B buttons so they do the same as select and back. You can do what you want with them if you need to. I have added the X and Y code if you want it for some reason:
    codes[96] = ‘select’ –button A
    codes[97] = ‘back’–button B
    codes[99] = ‘x’ –button X
    codes[100] = ‘y’–button Y

  6. Janni says:

    Hi, i tried both of the examples Ed provides here on my fire tv stick and none of them works with my fire tv remote. the key events work in the similator and i get the expected responses in the console. Did anyone succeed in using RGEasyFTV.lua this in his Fire TV apps for the Fire TV Stick Version? I build for amazon within corona and can install apps on the stick and they run fine. just the controls will not work at all. Tried both examples here. I am wondering what i do wrong or if i miss something. Thanks for any hint or at least the approval that the RGEasyFTV.lua actualy does work on the currently sold devices. Maybe amazon changed something?