Project Postmortem: Panasonic VIERA Connect (2)

This is the second of a four-part story documenting my somewhat excruciating and wholly uncharted experience developing an indie game for Panasonic’s obscure VIERA Connect television app market.

In the first part of this postmortem, I detailed the pains of becoming a VIERA Connect third party developer and struggles of setting up the rigid development environment required by Panasonic. Now I turn my attention to the actual development process using the company’s available API.

…Time to Make My Game

Apple Muncher Title Screen

Apple Muncher Title Screen

The idea for my game was simple—I wanted to recreate the classic snake game for compatible Panasonic televisions and Blu-ray players. My first encounter with this type of game was in the early 1990s via Microsoft QBasic, which included a sample application known as Nibbles.

The plot is as simple as it gets: collect items placed randomly on the screen and avoid crashing into barriers or your ever-growing self. The ‘snake’ genre was heavily popularized by early flip-style cellphones, many of which included such a game preinstalled to the thrill of bored people everywhere.

To add to the game’s addictive qualities and replay value, I decided to implement a few core features:

  • 25 unique and increasingly difficult levels
  • Five graphical themes to change the overall look and feel
  • An online score system to increase competitiveness
  • Several collectibles including different colored apples and extra lives

The player would start as a tiny snake and would grow so many units with each collected fruit, depending on the flavor of apple eaten. As the user progressed through each level, the base speed of the snake would also steadily increase. After some consideration, I decided to call my game Apple Muncher. [An early working title was Nibblify—derived from Nibbles and my first iOS app Scribblify.]

Hello Ajax-CE

Hello World - Ajax CEDuring the time that I was actively enrolled in Panasonic’s developer network, the only API available to non-partner developers was what Panasonic dubbed Ajax-CE. As detailed in the first part of this series, I was unable to view any part of the API before ponying up nearly $130. At some point after my development stint, Panasonic enabled free registration for users to review the API documentation before committing to the platform. Alas, with the promise of JavaScript-driven development, integrated 3D functionality and rich GUI libraries, I blindly approached the platform with a lot of hope.

Within minutes after skimming over the API documentation, my aspirations for the platform as a third party dwindled. It was immediately apparent that the partner apps on the VIERA market, including the stunning Asphalt 5 racing game from GameLoft, were not developed using the toolkit I was supplied with.

The JavaScript-based API was, in fact, a highly restrictive subset of commands tied to proprietary Panasonic object methods. It was impossible to output any HTML elements or CSS styles. The underlying concept of the API revolved around “Stages,” with each stage representing a particular screen or interface. A stage is represented as a JavaScript object with a handful of methods (i.e., an event handler for detecting user input, in/out transitional methods) and some properties (i.e., an array for housing media assets, a background image declaration).

The code required to display Hello World on the screen using Panasonic’s Ajax-CE, simulated in the screenshot above, is as follows:

For Apple Muncher, I would require three stages (equivalent to three screens in a typical app):

  • Title Stage: The initial stage where the user can set options or start a game.
  • Game Stage: The heart of the app where the user actually plays the game.
  • Score Stage: The list of high scores with some basic filtering options.

Interface Design

As a traditional Web programmer, I was accustomed to loading in media assets and manipulating interface components using the standard HTML/HTML5 Document Object Model (DOM), CSS styles and JavaScript properties. Since Panasonic’s Ajax CE does not support HTML documents or CSS, you cannot simply load up an image or generate text in the usual way. Instead Panasonic provides a custom means of creating a few basic media types:

  • gbox: A class for creating basic rectangle shapes
  • gtext: A class for creating basic single-line text labels
  • gtextbox: A class for creating multi-line text boxes
  • gimage: A class for displaying image-based media

These components are instantiated in the usual way of creating a new JavaScript objects. Each type supports a number of properties to control position and appearance. For example, when the snake eats an apple in my game and it needs a new body segment, I perform the following function to load in and position a new body segment image:

Apple Muncher Gameplay Screenshot

Apple Muncher Gameplay Screenshot

In the snippet above, I push a new gimage object into the playerBody array (defined earlier) to extend the player’s body length. Depending on what type of apple has been eaten, this function may be repeated several times to add numerous new segments. The properties used for the gimage instantiation behave as follows:

  • translate [X, Y, Z]: Positions the new body segment at the player’s previous x/y coord. This puts it where the head of the player was in the last frame, so new body segments descend from the head.
  • rotation [ANGLE, X, Y, Z]: Rotates the image the specified angle in degrees. You specify which axis to rotate around by designating ‘1’ in the pertinent area. I rotate the new body image so that it is the same direction as the player’s head so that it seamlessly blends with the rest of the snake.
  • src: The path of the image to use. To support basic themes in my game, each graphic is prepended with a number corresponding to the theme. I create the source path by concatenating the selected theme with the requested image. Sometimes the player may turn as they collect an apple, whereby a ‘turn’ body image is loaded, while other times a ‘straight’ image is necessary. I determine this prior to this function and store the image name in the bodyImg variable (i.e., “turn.png”).
  • width/height: The dimension of the gimage, in pixels. In this case I use the size defined in the player object so that it matches the scale of the head.
  • visible_p: Sets the gimage to be visible on the screen.
  • color [r, g, b, a]: The color to tint the image. With all values set to 255 the image will be its original color. The images I created were grayscale so applying a tint of 255, 0, 0, 255 will give it a full red tint. In the ‘plasma’ theme of the game, the color of each new body node is cycled, so I adjust the color values before adding this node and retrieve the RGB values from an array.
  • draw_type: This value of this property determines how the loaded image will scale if the width and height differ from the loaded image resolution. Inscribed will stretch the image to fit the specified width or height while preserving the aspect ratio. Circumscribed clips the image to the specified width and height while still preserving the aspect ratio. Direct will simply scale the image to the specified width and height regardless of aspect ratio. In my case the image is the same resolution as the size specified so it makes no difference.

After the gimage is created for the new body segment and pushed to the end of the playerBody array, I then push it to the components array of the main stage class. This is needed to actually render it to the screen. There are a couple other operations available in a gimage object including a ‘flip’ property to mirror the image horizontally or vertically, and an onload callback function that is triggered as soon as the image has loaded (which I use to track what images have loaded; ones that haven’t loaded after a certain time are requested a second time). You can revise these properties after the image has been created to move it on the screen, rotate it and so forth.

I use gimages for all of the graphical elements in the game, gtext/gtextbox objects for the score labels and high score charts and gbox for the preloader background. Due to the limited customization options available for text objects, I opted to create custom menu options using graphics instead. I also had to create a custom on-board keyboard for accepting user input for high score entry, given the lack of any native input field options available through the Ajax CE API.

Mind-Numbing Sound Effect Limitations

Panasonic's Ajax-CE Software-imposed Sound Limit

Panasonic’s Ajax-CE Software-imposed Sound Limit

Despite feeling that the available graphical feature-set was quite imposing and cumbersome to work with, I was still optimistic that the audio support through the API would at least be solid.  After all, this was a top-end 1080p smart television line with built-in apps that could stream 5.1 surround audio. The integrated speakers themselves  support up to 48 kHz LPCM audio.  The audio of Asphalt 5 sounded great through the machine as well. Yeah, right!

The Ajax-CE third party API in fact restricts audio formats to a jaw-dropping degree.  Specifically, the only supported audio format is 16-bit AIFF, 11.025kHz to 12kHz, mono!  I hadn’t come across such a harsh audio restriction since the earliest console days.  None-the-less, audio wasn’t a particularly big point in my game but I was still taken aback by this software-imposed restriction when the television was capable of so much more.  For Apple Muncher, I created two music loop files (Title, Game) and about six sound effects (Menu Toggle, Menu Confirm, Item Collect, Level Up, Death, Countdown).

The available audio command set is also scant.  You can do precisely three things with audio through the API: load a sound file into an indicated slot, play it (up to nine sounds simultaneously), and mute sounds globally. There is not even an option to stop a sound prematurely, nor one to loop a given file. To achieve looping music, it becomes necessary to run a timer for the precise millisecond length of the music file, then request to play the music again when the time has elapsed, infinitely. I had to implement some other inconvenient functions to appropriately switch between the two background music tracks I included, but below is a simple demonstration of essentially how I looped the main game background music.

Due to the comparatively large file size of raw AIFF files even at such a low fidelity, coupled with the fact that sounds cannot be stopped once they begin playing until they reach the end, I kept the music loops down to just two seconds for the title screen and six seconds for the game.

Level Design

Not wanting to do any more coding in the Ajax-CE platform than I absolutely had to, I decided to craft my entire level editor as a macro-powered Excel spreadsheet.  Within the spreadsheet, I would fill in cells with certain colors to depict certain elements in the map.  Red/Orange indicated walls and wall edges, green indicated the player start position.  The number inside the player start cell instructed the app what way the snake will be traveling when the level starts.  Each level had a configurable amount of total apples needed to progress, as well as a base speed for the map and how much faster the snake would go per apple eaten.

Apple Muncher Level Editor (Spreadsheet)

Apple Muncher Level Editor (Spreadsheet)

To generate the level data, I wrote a VBScript macro that parses all of the cells.  The script analyzes the walls and wall edges to determine what type of wall texture to place in the game to save from having to calculate any of that inside the Ajax-CE script itself. Before recording the wall data, the macro locates the player start position and records those coordinates along with the other vital level data.

You notice that I store all of the parsed data into a string that starts with levelData.push (.  After analyzing data about every cell in the level and appending the results to this string, the string is closed and written to a new text file using the following code:

The end result is a text file that contains a single line ready to be pasted into the Apple Muncher source code, appending the data as a new element in the levelData array.  It isn’t something meant for public viewing or deciphering and the whole line looks like:

On the back-end in the Apple Muncher source file, I parse all of these numbers based on the level being loaded and do what is needed based on the values retrieved.

Apple Muncher Gameplay Screenshot

Apple Muncher Gameplay Screenshot (Plasma Mode)

Odds and Ends

Panasonic did not provide any means to emulate the application being developed on a PC. Testing always had to be done through the Panasonic VIERA Connect app on the television itself, the complexities of which I detailed in part one.  This led to a couple development hurdles that I’ve come to take for granted in other platforms.

Console Logging

When developing standard JavaScript applications, I make heavy use of console logging to trace variables and help debug any issues that arise.  Every modern browser supports a developer console and DOM inspector and it is as simple as calling console.log("message") to send messages to the console.  To achieve similar functionality in an app being developed via Ajax-CE for Panasonic’s market, a few additional server-side scripts were required.  To Panasonic’s credit, they supplied these files and it was pretty simple to implement as long as your server was configured with Perl.   The steps to enable console logging are essentially:

  1. Copy the supplied Perl script to your cgi-bin directory and configure the Perl path.
  2. Copy the provided JavaScript file to the main app folder and change the path to point to the Perl script.
  3. Add an include to the JavaScript file from the main source file.
  4. Create a blank log file in a temporary folder.
  5. Log to the text file using the standard console.log() syntax.

This essentially sends POST data back to the Perl script every second, and the Perl script then writes the data to the log file.

Screenshots

Part of the app submission process required the production of five screenshots.  This was easier said than done as Panasonic did not provide any documented way to capture the screen as an image.  Since the app must run through the VIERA Connect market embedded into the TV, it was not even possible to run the signal through a capture card.  It would have been fantastic if Panasonic could have incorporated a simple function to save the screenshot to the server or memory card.  As it was, I ended up taking photographs of my TV screen and then cleaning them up to produce most of the needed screenshots.

Memory Card Access / Data Storage

Speaking of memory cards, one key bit of information absent from the API documentation is how to read or write data to the device for storing user preferences.  I had assumed before purchasing the Panasonic developer license that I would be able to store and retrieve data from the internal or SD memory card just like the GameLoft games had done.  Not so. As it is, the Ajax-CE platform for third parties does not publicly disclose how to write data to the system in any way, shape or form.  You can make simple HTTP requests from the app to send data to the server and back, as I do for the high score records, but saving user data locally is more shrouded in secrecy.

Apple Muncher High Score Page

Apple Muncher High Score Page

I inquired to Pansonic about this specific point. In my app, I simply wanted to save the last entered high score name when the user exited the app as a convenience to them. I was advised that I could indeed save credential data and other basic information to the internal flash memory, but that the part of the system is sensitive so the solution is not published to their portal.  They did supply me with the needed script and API functions for doing so, but I feel like this is a crucial part of any app and should not be invisible to third party developers and it would have been nice to interface with the SD card as well, if one was installed.

In the next installment I will detail the long and drawn out submission and approval process.

2 thoughts on “Project Postmortem: Panasonic VIERA Connect (2)

  1. Pingback: Project Postmortem: Panasonic VIERA Connect (3) | Matt's Repository

  2. Pingback: Project Postmortem: Panasonic VIERA Connect (1) | Matt's Repository

Leave a Reply