Wednesday, October 9, 2013

Firefox OS Easier Than Before (Game Programming)

I tweeted a few months ago about building a simple Firefox OS app and it sure is easier than it used to be. When I made an app, it gave me weird errors I was told to ignore. I didn't have an icon (and I didn't have a phone either). But now here I am, and the steps are relatively easy to follow.

So, here they are. If you have problems with them, let me know. The Firefox OS programming documentation isn't bad except that there are pages done at different times and things have disappeared and other things have appeared.

The main link for developing is here: https://marketplace.firefox.com/developers/

I've done programming for Android, iOS, Apple, Windows, HTML5, and lots of others. But the startup costs for Firefox are still the lowest and easiest. You need:

1. A simple text editor. I like Notepad++ and the price is ... free!
2. Firefox browser. Again, free!

I needed an art program to make an icon and I had an old copy of Photoshop 6 lying around, so that wasn't free. If there's any interest, I'll investigate some free art programs.

So here are the steps to make an app that you can test in the Firefox OS Simulator.

1. Get Firefox! You probably have a version already, but it would be good to get the latest. I downloaded 24.0 just for this test and it works great. I didn't have any plugins, not even Firebug.

2. Next, download the plugin for the Firefox OS Simulator. Get it from here:

          https://ftp.mozilla.org/pub/mozilla.org/labs/r2d2b2g/r2d2b2g-windows.xpi

     This is the Windows version but they have versions for Mac and Linux.
     Read all about it here:

          https://developer.mozilla.org/en-US/docs/Tools/Firefox_OS_Simulator

     Install it as an add-on extension.

     Then run it from the Web Developer menu and select Firefox OS Simulator.

     It should look like this:

    

3. Next prepare a few files. You will need to make the following:

     a. A simple text file named index.html. This will contain your code.

     b. A simple text file named manifest.webapp. This will contain information needed by the OS.

     c. A not-so-simple icon art file that will have a picture of the icon for your app.

4. Prepare index.html. This is the start of your program but it is really a simple HTML5 web page.

    Here is the code for your app. Change it around any way you want as long as it remains HTML5.

     <!DOCTYPE html>
     <html>
     <head>
         <meta charset="UTF-8">
         <title>Hello Firefox!</title>
     </head>
     <body>
     <h1>Hello Firefox</h1>
     <p>This is an application for Firefox OS</p>
     </body>
     </html>

All of this is standard HTML5 boilerplate and actually it is pretty much straight HTML except for the first line which is a command that tells the browser that this is an HTML5 program. It won't matter for your program, but when you expand, you'll want to take advantage of all the HTML5 goodness.

Oh, do put in the line about charset="UTF-8" since this seems important for some locales. You may know more about this than I do. I left it out and Firefox complained (good world citizen that it is).

5. Prepare manifest.webapp. This is a special file that is still just a text file. This tells Firefox OS about the app. Here it is:

     {
       "name": "Hello FFOS",
       "description": "Firefox OS gets better every day!",
       "launch_path": "/index.html",
       "icons": {
            "128": "/images/icon-128.png"
       },
       "developer": {
            "name": "Your Name",
            "url": "http://www.yourwebsite.com"
       },
       "default_locale": "en"
     }

This seems a little confusing, but just get all those brackets, quotes, and commas in the right place. 

You should change the following text to match your own app:

     name - the name of your app as it will appear when published

     description - a short description of what your app does

     launch_path - this is the place and name of where the OS will look when starting up your app.
                           (don't forget the /  which is the root of your app)

     icons - the name and location of your icon. I put it in a folder called images

     developer - your own name and the location of your web site (not required but smart)

     default_locale - I picked English but you may want to have another locale

I've given you the minimum manifest that seems to work.

6. Make an icon. I had some trouble with this because I just made an art file that was 128x128 pixels and saved it as a PNG. It didn't work. Then I found this well-hidden page that explained:


At the bottom of a long page that explains some art terms I didn't know, I found that I could download some sample icons in Photoshop format (PSD). I had an old copy (Photoshop 6, older than you!) and used that. I tried Paint.NET and that didn't work, but I'll see if I can figure out more later.

The point is that the icon has to have a few pixels free around the edges and that the edges have to be transparent. So here is my icon, modified from the one in the Firefox styleguide:


This is 128x128 pixels with some room to spare.

7. Next, put all the pieces together in a directory. Call the folder whatever you want, but make sure you can find it later. I called mine hello.

Then put your manifest.webapp and your index.html files in the hello folder.

Then make an images folder inside the hello folder and put your icon file there. Mine was called icon-128.png and the manifest says it is in /images/icon-128.png.

8. Finally, start the Firefox OS Simulator and find the button near the top that says Add Directory. Click it and find the directory you made (hello). Inside that directory, click on manifest.webapp and the app will load.

If all goes well, you'll see a little window pop up with your new app:


That's it!

Give it a try and let me know if you have any problems. I'll update this if I find out more.