5 Useful Resources (for WordPress)

My topic was "5 useful resources" for wordpress, and originally I was going to start off with version control with svn or git - but I later decided to tone it down a little and focus on things that would help non-developers (which ended up being a good decision).  Here's what I finally settled on:

#1: Balsamiq Mockups

Balsamiq Mockups is an AIR-based cross-platform program / web-app with the sole focus of making the conceptual design process smoother.  It allows you to focus on the main elements of a website (or app) without getting caught up in the small trivial details.

Here's a good example of how Balsamiq can be useful.  The design above (credit: http://dhrandy.deviantart.com/gallery/#/d24j5v8) is a typical mockup you may create for a client or yourself.  If the client isn't picky about design, then this can be a very fast way of getting things done.  However, if you present a website mockup in the beginning stages, and really just want to get the layout down as opposed to the final design - then sometimes you can get caught talking about what fonts to use, gradient colors, which images to use, etc.  I've been in countless meetings that had to wrap up without much progress because of so much focus on these trivial details early in the process.  Here is why Balsamiq Mockups is so awesome.

As you can see nothing on this mockup can be taken literally, and instead of discussing gradients or logo treatment, we can focus on the overall design first.  This is one of the most useful tools I've discovered in the past few years, and it truly does make life much easier.  It's  extremely easy to use, so that non-designers and non-developers can flesh out ideas in detail, without getting overwhelmed or losing their concepts in translation by technoical jargon.  Most of the time, the benefit of using Mockups can be seen instantly - the first project you use it on.  It's a paid product, but there is a free 7 day trial, which should be more than enough time to decide whether it's right for you or not.

#2: LastPass

LastPass helps you deal with the endless number of passwords to keep track of.  Aside from personal passwords to remember, some of us may also have long lists of personal or client blogs to manage.  Not just that, but to be secure about it - each password really should be unique.  Oh, and passwords should not be kept in plaintext files.  So what the hell is the solution?  This one is easy.

LastPass not only keeps track of all your logins, but it can login automatically for you across all browsers, platforms, and mobile devices.  If you have an internet connection, you will be able to login to any website you need to.  It's pretty self explanatory and well worth looking into.  A couple people at the meetup mentioned similar solutions like KeePass, which is essentially the same idea however LastPass is used strictly within a web browser, and stores passwords for websites.  KeePass and similar programs can actually store much more information like credit cards, serial numbers, etc. however I haven't found anything else out there which is as easy to use as LastPass.

 #3: Using a VPN (Virtual Private Network)

Every once in a while, a site that should be up, just magically goes down.  No response, nothing.  Also, sometimes a site will look fine to me but a visitor or client will swear they can't get to it.  Is it cached?  Network problem?  Who knows?  The very first thing I do is check a website called "DownForEveryoneOrJustMe.com" although it's also got a much shorter URL:  IsUp.me

Most of the time, the site is up and there is just a temporary network issue somewhere along the line.  However, if you are ever wondering if a site is being blocked, filtered, or just down for you - this is a quick way of determining the answer.  That brings me to the real solution though, in case you are being filtered or blocked for some reason, VPNs can help out a lot.  To anyone that has to work behind a firewall or in secure environments this isn't anything new - however even if that doesn't describe you, VPNs can be incredibly useful.  The solution I currently use is WiTopia, since they were rated best on Lifehackr and had very competitive prices.

The other big advantage of WiTopia was the number of locations you can connect from.  Basically, your internet connection is routed through one of these locations, so you can bypass caches, firewalls, and see for yourself if there are problems with your website.  Not to mention, this also allows you to access sites that are otherwise international.  If you've ever tried accessing American media from overseas and been blocked due to copyright laws, this fixes that as well (and vice versa - as someone asked if this would allow you to watch BBC videos online from within the US - yes!).

#4: Dropbox + Portable Apps

Another Resource which is part of my everyday routine is Dropbox, especially in conjunction with portable apps. In a sentence for anyone not familiar - dropbox is basically a folder that keeps all files inside of it synchronized across your computer, laptop, mobile devices, etc.  Traditionally it's used for sharing documents, backing up files, etc. However it can also be used as a "usb thumb drive" that sits in the cloud, which you can install software to.

The specific software I mentioned was HeidiSQL, Notepad++, and FileZilla, although here is the full list of portable apps I have installed on my dropbox:

• FileZilla (FTP/SFTP/SSH client)
• HeidiSQL (SQL client)
• HostsMan (edit windows hosts file easier)
• PuTTY (telnet/ssh client)
• Skype (instant message client)

A great resource for more apps is PortableApps.com:

#5: WordPress Migration Script

Here's a scenario that can be a pain.  If you are putting together a wordpress site locally on your machine before pushing it to a production server, during the database migration any text referencing your old localhost address could still need to be updated.  The Migrate script makes that much easier.  All you do is enter the current URL, then the replacement URL, and hit go.  The script will detect any changes that need to be made before asking you to confirm them.  This is also very helpful for moving a blog to a new domain name.

https://github.com/ErisDS/Migrate

Bonus! WP Smush.it

This was something I had never heard about before the meetup, and an awesome tool I've already implemented on this website: WP Smush.it.  It basically just compresses all of your image files for you, and can do it in one big batch.  Within 5 minutes I had installed it, and used it to compress all uploaded images pretty easily.  Highly recommended!

Conclusion

The wordpress meetup was great, and I'm looking forward to many more meetups in general.  BarCamp Orlando is next month as well, which is like a 100 meetups in one, spread all over downtown Orlando bars and pubs.  I'm not sure how many locals check out my blog, but if you're in town - make sure to be there!

As a quick preview, here are some of the books and documentaries I'll be reviewing soon:

Documentary: Kubrick's Odyssey

http://www.youtube.com/watch?v=qySnL38JpOg

Created by Jay Weidner and produced by "Cubed Brick Productions" (get it, Kubrick?  Cubed-Brick? ha... anyways...) this documentary is extremely fascinating.  Without giving away all the best parts, it's about how Stanley Kubrick was offered the job to fake the Apollo 11 moon landings in a soundstage.  The argument is made that through photo analysis, the same exact technology used for the moon landing shots was later used for 2001:  A Space Odyssey.  Specifically, the technology was a 3M fabric coated with very tiny mirrored beads of glass which acted as a backdrop for the scenes, sort of like the first version of chromakey (aka "green screen").  Furthermore, this documentary tries to show that The Shining was Kubrick's attempt at exposing his involvement in one of the biggest coverups in American history.  Best of all, this documentary is just one in a series aimed at decoding all of Kubrick's work, up to and including the movie that "killed him," Eyes Wide Shut.

Book: A Terrible Mistake

The whole title is a mouthful: A Terrible Mistake: The Murder of Frank Olson and the CIA's Secret Cold War Experiments by H.P. Albarelli Jr.  This is one of the best reference books on the subject of MKULTRA that I've read to date.  MKULTRA was a Top Secret CIA program originally started with the OSS's (precursor to CIA) search for a truth serum, and eventually evolved into a large umbrella with over 140 different subprojects.  The movie The Men Who Stare at Goats is based on an actual experiment called Project Stargate, which was rumored to be an offshoot of MKULTRA.  A Terrible Mistake revolves around the death of a chemist located at Ft. Detrick in Maryland, that was dosed with LSD and then assassinated by a CIA agent.

Book: Sinister Forces Trilogy

This is an extremely detailed trilogy by Peter Levenda.  It's hard to wrap it up in a few sentences, but I'll do my best.  Levenda traces the roots of American politics, crime, and culture all the way back to the beginnings of human history.  This book covers stories from ancient Egypt, Knights Templar, Rosicrucians, Arawak natives, Salem witch trials, all of the world wars, all the way to Jim Jones, Lee Harvey Oswald, Nixon, and Charles Manson.  While this sounds like a huge range of unrelated groups and people, the entire focus of Sinister Forces is to tie these things together.  It really is a fascinating read.

And more!

For the record, I'm not very interested in alien abductions and UFOs, although I am quite interested about our ancestors' perspective on the stars, like the Dogon tribe's ancient knowledge of Sirius.  Most of the books I like reading are more about industry (oil and railroad barons), military and CIA operations (MKULTRA, Iran/Contra, etc.), secret societies (Freemasons, Adam Weishaupt's Bavarian Illuminati, "The Finders", etc.), and next-level weapons (HAARP, electromagnetic mind control, etc.).  In fact, the subject of mind control is of particular interest to me, as there are so many parallels to software engineering, not to sound creepy about it.

Hopefully some of you will find this stuff interesting.  If not, don't pay these posts any mind as I will be mainly focusing on code, tutorials, and other tech related stuff as I usually do.

Since starting with Corona SDK in 2011, I have really taken a liking to it. It hasn't replaced my other solutions yet , and I'm not sure that it ever will.. but truth is, it doesn't have to replace anything. Corona seems to be in a good niche all to it's self, despite the pugilistic attitude towards Adobe's Flash/AIR/etc. Unlike Flash however, which has a robust IDE and large suite of complimentary applications (Photoshop, After Effects, Illustrator, etc.) Corona is bare-bones, really just an API bundled with a simulator and compiler. Once you get comfortable with the basics of Corona and are ready to dive in a bit deeper and make your workflow easier, here are some great tools:

Software

Various software that can save time and really help out specifically with Corona development.

1. TexturePacker

(texturepacker.com - free version available, Pro: $24.95)

TexturePacker is essential for creating spritesheets in Corona (it also exports to Unity3D, css, json, cocos2d and others).  To put it simply, TexturePacker allows you to drag and drop a folder full of images (swf, png, jpg, bmp) and automatically create a spritesheet / tilesheet image, and an exported program specific template.  There are quite a number of options to set, such as layout algorithms, padding, trimming transparency, and a host of other optimizations.  Personally, I found this useful when creating large spritesheets of animated assets - for example, the sheet below:

Final Thoughts:  If you need to create lots of spritesheets, the $25 spent on this program will repay itself after the first hour or two you save yourself in time and frustration.  I cannot recommend this program enough to anyone creating sprite-based games in Corona, or any other program for that matter.

2. PhysicsEditor

(physicseditor.de - Paid: $19.95)

Made by the same developer as TexturePacker, this tool is used to automatically create physics objects from image files that have transparency.  You simply drag and drop an image into the program, and trace it yourself or use the auto-tracer.  You can set physics attributes (density, friction, etc.) for each object, and even collision filtering.  After you are done setting all the shapes and parameters, it outputs all of the physics data to Corona SDK format (along with many other formats, including QuickBox2D for AS3/Flash, Box2D, and more).

Here is a screenshot of the automatic tracer, which will outline your object using the transparency in the image.  This features saves lots of time.

Final Thoughts: This program is another must-have for anyone creating physics-based games.  There are a few other solutions out there (some even free) but I've found this to be the easiest to use, and the only one which exports into various formats easily.  This program has saved me countless hours of tedious work, and will do the same for you.

3. JetBrains IDEA

(jetbrains.com/idea - Free)

One of the very best IDEs for programming in Lua (and Corona SDK) for Windows.  It supports auto-completion, code hinting, syntax coloring, all sorts of awesome features.  I use other JetBrains software (PhpStorm) as well, so it felt very natural to me.  The layout and feature set is very similar to NetBeans or Eclipse.  Since the various features and setup is a bit more complex, take some time and read over the tutorial I wrote on Corona SDK development on Windows, where you can get a better idea about... err, IDEA.

Final Thoughts: In my opinion, there really aren't many other options out there that can compare with IDEA for Corona developers on Windows - especially considering the price tag (free).  If you're on Windows and not using IDEA for Corona development, you're in for a real treat!

Update (05/09/2012):  There is a new solution made specifically for Corona SDK developers, Corona Cider by M.Y. Developers.  At the launch price ($29), it's a steal.  I have not been using it as much as IDEA yet, but I can see it becoming my primary Corona IDE with some more polish and features.

Third Party Libraries

Some Corona code libraries which save time and add some great features.

4. TextCandy

(x-pressive.com/TextCandy_Corona - Paid: ~$54)

Another common element of game development are bitmap fonts.  Even if you aren't creating games, using custom fonts can be a huge hassle for mobile devices.  By using TextCandy, you can add support for custom fonts easily, along with a very long list of additional features for animation of text.  The developers claim that it's not meant for text-heavy applications, more intended for animated text or other special treatment.  For game development, this is an incredible tool.  It also works very nicely with TexturePacker, for creating your own custom bitmap fonts.  The code is very clean and optimized for Corona projects.  It's officially supported on the Corona SDK forums, and is actively maintained.

http://www.youtube.com/watch?v=AjrWRWc0ivg

Final Thoughts: If you need animated text or custom bitmap fonts, this is worth every penny.  Note: If you buy TextCandy, you can purchase ParticleCandy for 50% off.

5. ParticleCandy

(x-pressive.com/ParticleCandy_Corona - Paid: ~$54)

From the same developer as TextCandy, this as you can gather from the name, is a particle engine for Corona.  Originally based on Blitz3D (another game development solution), this is a light-weight and high performance library that supports sprite sheets, texture atlases, unlimited emitters, emission shapes, scaling, sounds, particle types, and too many other features to list.  Simple answer to this one is, if you need particles in your Corona project, and don't have the time, knowledge, or means to create your own particle engine, then this will be the best (and most impressive) $55 you can spend for an immediate solution that looks and works great.  The level of customization for this library is ridiculous, and I can't recommend it enough.

http://www.youtube.com/watch?v=kq4eFVOvr0Q

Final Thoughts: If you need animated text or custom bitmap fonts, this is worth every penny.  Note: If you buy TextCandy, you can purchase ParticleCandy for 50% off.

6. Lime (beta)

(justaddli.me - Beta: $27, Final: $54 )

This is a library that has so many features to make creating tile-based games easier, that it's hard to not recommend it.  Except for one thing: performance.  While this library offers a long list of enhancements (not the least of which are tile support, camera control, animated tiles, map loading, etc.), unfortunately a lot of those features are negated due to how poorly tile-based games perform using Corona in general.  This is not necessarily a fault of the Lime library.  In fact, when using Lime in the Windows / OSX simulator, everything runs very smoothly.  Only when you build to device to the issues start to become present (especially on Android devices, which are generally slower than iOS when using Corona).  There are a number of projects already released and fore sale using Lime, so it's not worthless by any stretch - however it's not the simple solution it seems to be, since there is quite a bit of optimization you have to do which can cancel out any time saved with Lime.

Final Thoughts: Since this isn't exactly the fault of Lime as much as it is the way Corona handles display objects (no support for blitting) it's hard to fault the developer.  However it also makes it hard to recommend, even at the discounted "beta" price of $27.

7. Crawl Space Corona SDK Library

(crawlspacegames.com/crawl-space-corona-sdk-library - Free)

I d haven't had a lot of time to play with it, but this library should be compatible with the most recent builds of Corona (as of 2/25/2012) and adds lots of great features including fadeIn() and fadeOut() helper methods, timer managers, loading/saving data, music managers with fading, etc.

Final Thoughts: Since I haven't had a lot of time to experiment, the jury is still out on this.  However since it's free, it's well worth the time to check it out!

8. Simple Analog Stick Module (lib_analog_stick)

(developer.anscamobile.com/code/simple-analog-stick-joystick-module - Free)

Here's a free library, since the rest all cost money.  This is a really useful virtual joystick module which allows you to create as many touch-screen joysticks in your game as you want.  It supports functions like getDistance, getPercent, and getAngle for figuring out how the user is interacting with each of the sticks.  It also has a very easy way to move an object with a stick, by simply calling Stick:move(player, 5.0) where player is the object to be moved, and 5.0 is the speed.  For prototyping, it's so easy to just add this to a project and get going.

Final Thoughts: For the price, you'd be insane not to check this out!

Debugging Tools

Tools to make your life easier during development and debugging.

9. Corona Ultimote

(mydevelopersgames.com - Paid: $16.99)

This is an Android and iOS app (you get both after paying), which allows you to stream device messages (like multitouch, GPS, accelerometer, etc.) to the Corona Simulator when developing and testing.  Instead of building to the device each time you want to test an app, you can do it live in development.  The process isn't perfect, however it does save lots of time in building and testing, so for that alone it's worth the price of admission.  Another cool feature is that Ultimote will actually stream images to the device as well, so you know where to touch the screen and etc.  Again, this tool seems like it's a bit unpolished and under development, however it also seems to be the only solution for Corona SDK that supports both Android and iOS.

http://www.youtube.com/watch?v=fZBjw_8100o

Final Thoughts: If you are developing anything that relies on physical sensors or input (orientation, multi-touch, tilt, compass, etc.) this is one of the best tools you can get.  Since it includes both iOS and Android apps (along with a Corona Lua script), this really is one of the only options out there anyways.

10. Corona Profiler

(mydevelopersgames.com - Paid: $9.99)

Another product from M.Y. Developers, who also make Ultimote.  After your app or game is mostly done, then begins the real hard part: testing, debugging, and optimizing.  Unfortunately, one of the biggest issues with Corona development is the lack of a great debugger.  The Corona Profiler helps bridge that gap a little by creating a detailed interactive report, which allows you to trace where all the memory and processing is going during your app execution.  It's very helpful in ferreting out memory leaks or singling out functions that need to be optimized or broken into smaller steps.  Unlike the other tools mentioned so far, this doesn't automatically make your project better, but it does make your life easier when you want your app to run faster, but don't know where to start.

http://www.youtube.com/watch?v=ft2fObkahN4

Final Thoughts: Very much worth the $10 it costs in every way.  Typically, the debugging and optimization steps in game development take the longest.  Any tool out there which can make this any easier is worth its weight in gold.  But since this is an intangible product, let's just say it ways at least $10 in gold and worth every cent.

Bonus: Photoshop

(photoshop.com - Paid: $699)

This shouldn't be a huge shocker, but Photoshop (or any other image editing program) is essential to create the graphics you need.  Also, since the price tag is the better half of $1,000 it may not be a viable solution to many readers.  In that case there are many other options out there which are free or at least much cheaper.  I just want to point out a big caveat for anyone using photoshop for Corona Development.  IMPORTANT: Save all your graphics as PNG and DO NOT use "Save for Web!"  I cannot stress this enough.  Saving your graphics with "save for web" can cause a long list of unexpected and inconsistent issues, specifically with iOS.  I spent more time than I should have figuring out the hard way, that the PNG files I was using on Android in Windows, didn't work on the OSX simulator and consequently, anything I exported (iPhone, iPad, Android, etc.) didn't load properly either.  Certain PNG assets would simply show up as all white.  After a few bug reports submitted, and trying various PNG tools I realized the problem went away after I stopped saving for web.  Save yourself some time and learn from my mistakes!

Final Thoughts: Use whatever you want.  Just be careful on how you export your images, and be sure to test across platforms and devices.

Conclusion

To be up-front, I have not been paid or solicited in any way to review any of these products. Also, I realize that the tools that work for me may not work for you (or vice versa).  There are also a number of products out there that I haven't evaluated yet (e.g. Corona Project Manager, Spriteloq, Kwik, etc.)  The main reason I haven't checked these out, is because they aren't free, and I haven't had an immediate need for any of them.. yet.  Spriteloq seems to serve a similar purpose as TexturePacker, except it exports animated SWFs to spritesheets.  Corona Project Manager is a little like an IDE but lacking in robust features although it caters specifically to Corona projects.  Finally Kwik seems like a really great plugin for photoshop users - essentially allows you to create animations and interactive apps within photoshop and export to Corona.

If you have any questions, problems, or suggestions regarding anything mentioned above, please leave a comment!

P.S. Allow me to apologize about any abundant alliterations in the title.

With that said, the first game is actually part of a larger project I'm working on, but the general game design is a bit like a fast-paced Gun.Smoke:

http://www.youtube.com/watch?v=MzPlGJ85jCM

The biggest things I'm struggling with now are the controls and orientation.  Currently, there is a virtual joystick in the lower right corner to move the player.  I've tried just using the touch screen, but then your finger covers up more real estate when playing.  The real estate issue is the same reason I took away the left/right fire buttons on the left.  I'm also deciding on whether or not to allow the player to shoot left and right, or restrict the player's attack to straight up (like 1942).

http://www.youtube.com/watch?v=4eK7K3xtVms

The funny this is that when creating similar games in AIR, I would have still been messing around with compiling and optimizing, so worrying about game design and UI issues is a welcomed task.  On the other side of that coin, when I needed to make a wave (level) editor for my game the first thing I thought of was Flash/AIR , which worked out great.  With the wave editor, I'm able to start putting together some strategic layouts.  There's no real AI for any of the enemies yet, but I do plan on adding that soon too.

Since the top-down shooter project is probably going to take at least a few more months, I've also started on another game.  While it's starting out as a Peggle Clone (which I'll probably use to write a detailed Corona SDK tutorial), I've got a few ideas in mind of where I'd like to take it eventually.  I'm hoping to release this one as soon as March, and continually update and improve upon it.  For a quick preview of where I'm at after 6 hours, here's a video:

http://www.youtube.com/watch?v=gWjiUPssHSQ

Finally, it's been a while since I last posted - and due to the holidays, it may be another while until the next one.  So just to throw out there... I've also been working a LOT with AIR/Android development, along with using PhoneGap and jQuery Mobile with a few projects.

I realize that so far this blog might seem a bit Flash/Corona biased, but there are so many other cool projects and technologies I've been working with, that I can't wait to write about soon.  Thanks to all the new readers that have been visiting, and feel free to drop me a message/comment about any tutorials or articles you'd like to see.

Yesterday at Adobe MAX, Adobe announced a major upgrade with AIR 3.  Along with a host of improvements and new features, the main ones that caught my eye included "new architecture for high-performance 2D/3D GPU accelaration," and improved mobile support.  Actually, those two items combined highlight my biggest concern with AIR - performance.

For making productivity or utility apps, AIR is a great choice (depending on the level of control you need over native functions).  However for mobile apps that involve lots of movement and listeners (i.e. games), it hasn't been as much of an option.  The performance issues alone turned my interest to Corona SDK, since it allows developers to target multiple devices with the same code and assets (and maintain performance to an extent).

However, the latest update to AIR seems to be a HUGE step in the right direction.  Without changing any of my actionscript at all, and by simply updating my mobile devices (EVO 4G, Nook Color) to AIR 3, I had an instant performance increase.  To get a better idea of the actual performance increase, I need to add some FPS/memory logs and run them again on the older and newer versions of AIR.  However I can say without a doubt, the performance increase from AIR 2.7.1 to AIR 3 was substantial enough to get excited about.

The Stage 3D rendering is still only supported on personal computers and TVs (oh yeah, the other big announcement was the integration of AIR into TV sets) but should be coming to mobile/tablets soon.  That's not really a big issue for me, since I haven't ventured much into 3D mobile apps outside of a few Unity tutorials.  However, all of this is really good news for Flash and ActionScript developers.  Not only is Adobe pushing for more and more device compatibility, but they are also focusing on many performance issues that seemed to have taken a backseat over the years.

Corona SDK vs AIR?

To me, the Corona vs AIR debate was largely centered around device compatibility and performance.  The simplified use of Lua that Corona uses certainly makes life easier, but if performance is no longer an issue with AIR, then it's more like Corona SDK vs FlashPunk, or Corona SDK vs Flixel. I'm assuming Corona still does outperform AIR, and  this isn't to say that Corona won't continue to outperform AIR as time goes on.  However, it looks like Adobe is making lots of progress and the gap is starting to close.  I'm not the only one that's constantly torn between the too either.

Of course, I became a subscribed member of Corona SDK the day before this huge announcement, and now own a license for both Android and iOS development... so I'm still just getting started with Corona, and don't intend to stop.  However, since I prototype most of my games in Flash first anyways, I'm looking forward to perhaps skipping the Corona porting process altogether for certain future projects.

Here is a quick description of the perfect HTPC / Media Server: Something that can automatically download, repair, extract, gather information on, rename, sort, and play back movies, tv shows, albums, ebooks, games, and even comic books - while making all of the content remotely accessible via browser, mobile-devices, etc.  Oh yeah, and it should be able to run 24/7 while using less energy than a (incandescent) light bulb.

While there are a million and a half ways to setup an HTPC (Home Theater PC) / Media Server, I'm pretty satisfied with my current setup, so I thought I would share.  In a nutshell, I built a mini-ITX system (for less than $400, which runs at less than 50W) running a combination of Sabnzbd, Sick Beard, Couchpotato, Subsonic, VNC, XBMC, Maximus Arcade and a few other small utilities.  With an exception to Maximus Arcade, all of this can be setup using any hardware/OS combination (Windows, OSX, Linux) that supports Java and Python.

Defining Needs / Requirements

Since HTPC / Media Server is slightly vague, here are the specific features I wanted:

Automated Downloading of Movies / TV - Specifically, a way to simulate the functionality of a DVR, without any need for cable TV.

Remote Accessibility - Being able to access/share my media library from the road, work, cellphone, wherever - and only using VNC as a last resort.

Low Power Usage - I wanted to build a machine that could be left on 24/7, without concerns about electric bills or overheating.

Easy to add media, or send links for downloading - Sometimes you think of a show/movie/album you want when away from your computer (at a party, on the road, dinner conversation, etc.)  Having an easy way to add items you want remotely is a very attractive feature.

Ability to Play Emulators and ROMs - For me, no HTPC would be complete without the ability to play old console (NES, Genesis, PSX, etc.) games.

From Cable & DVR, to Usenet & Sabnzbd

It's funny how technology can change behavior over time.  Back when I had cable, and before I had a DVR, there were only a few ways to catch a movie/tv show - either plan on being home to watch the show/movie when it aired on TV, or rent a DVD / stream from Netflix (assuming the video you want is available, and not too recent).  Then, after getting a DVR a few years ago, planning my schedule around when a show came on was out the window.  It was a liberating feeling, and let me catch up on shows when I had the time to do so.  Not to mention, being able to fast-forward through commercials was a bonus.

After a while though, the novelty of a DVR wore off, especially as the rate and taxes for Cable TV continued to rise.  Not just that, but if you ever look into subscriber fees associated with cable, you'll notice that the rates for the various channels is far from equal (e.g. ESPN costs around $4/month, while the Science Channel costs only $0.06/month).  So unless you are a heavy sports fanatic, chances are over half of your cable bill is going to channels you'll never watch.  I definitely fall into that category, and the linked Consumerist article played a huge factor in motivating me to look for other solutions.

Newsgroups

Enter Newsgroups.  Most netizens are familiar with direct downloading (e.g. forums, ftp sites, rapidshare, filesonic, hotfile, etc.) or p2p (limewire, torrents, etc.).  In fact, just about anyone who has downloaded a digital movie or album online outside of iTunes, has probably done so via direct downloads or p2p.  While those are easy and popular options, the reliability and quality of the files, and most importantly - security of the process, are all very questionable.  Download sites keep track of IPs, and are riddled with misleading links and malware scripts.  Torrents have slightly better quality control, but they are also probably the biggest source of copyright infringement lawsuits.  This is because by design, when you download a torrent you are also uploading that torrent to the rest of the world (making you a source for potentially pirated media).

While newsgroups don't completely solve all of those issues, they get close and have other advantages.  Most people don't even realize they already have newsgroup access with their current internet provider.  Of course, the free access provided by ISPs is very limited, and not anonymous/secure, so this is where a premium usenet provider comes into play.

Premium newsgroup access is typically secure and much more "anonymous" than any other method of downloading (depending on who you get newsgroup access through, and your router/network setup).  The other big advantage is that most usenet providers allow you to download as fast as your connection will allow (as opposed to torrents, which are limited to the speed of your peers).

There is an inherent learning curve when dealing with newsgroups, and user-friendly clients have only started becoming more and more refined over the past few years.  At some point, a friend pointed me towards an automated usenet downloading solution called Sabnzbd.  This actually takes lots of the "manual labor" out of usenet.

Costs?

As you might have assumed from the name, "premium" newsgroup access is not free.  It ranges from less than $10 per month to over $30.  For the best of the best, I would suggest Giganews, which ranges from $5 to $35 per month.  Second to that, is Supernews, which is run by the same company.  Supernews offers a single unlimited service, for a flat rate of $12 per month.  There are lots of other options, such as UsenetServer and Astraweb.  Both have good reviews and are perfectly decent alternatives.

So what is the actual cost of all this?  Well the average digital cable TV bill is around $75 per month.  Add internet access, premium channels and a DVR, and the cost easily rises to over $100.  That's not even taking into consideration subscriptions to other services like Netflix and Hulu.  Similarly, the average high-speed internet connection bill is around $75 per month.  By adding another $10 for usenet access, you can have so much more, for so much less.  $85 per month is about the top-end of what you would pay for an unlimited selection of tv shows, movies, music, games, etc.  There are some other small costs here and there too, such as an NZBMatrix subscription for $12 (for 5 years).

Introduction to Sabnzbd

Sabnzbd (which stands for SAB nzb daemon) is basically a python service which runs in the background, and makes monitoring, downloading and uploading files extremely easy.  The entire app runs as a webservice, and is accessible via the browser (e.g. "http://localhost:8080").  Just like a .torrent file is simply an indexed list of links, newsgroup binaries have indexed links saved as .nzb files.  Normally when using an NZB file, your newsgroup client (e.g. Newsbin Pro, Unison, etc.) will find all of the "parts" in the NZB, and then download them.  Depending on the newsgroup client features, the program may also assemble file parts, repair them (using .par2 files or recovery records), extract them (unzip, unrar, etc.) and even delete the original files (the leftover .rar, .zip, etc.)  Truth is, since using Sabnzbd, I don't have a need for usenet clients anymore.  Sabnzbd will do all of these things (assemble, repair, extract, delete) and much more (such as renaming, sorting, etc.)

Getting Sabnzbd to download stuff...

So you have sabnzbd installed and setup.  How do you get it to actually download something?  That's actually the easy part!  There are three main ways to send files for sabnzbd to download.  First, you can just click the "add nzb" button at the top of the screen.  From there you simply upload an .nzb file directly, and sab does the rest.  The second way of sending nzb files to sab is via a "watched folder."  This is a folder somewhere on your system (e.g. "C:\downloads\nzb") that sabnzbd will constantly monitor for files.  As soon as it finds an .nzb file, it will add it to the list of items to download.  The third method is to setup an RSS feed through a site like NZBMatrix.  More on this in a later tutorial.  Those are the basic ways to get sabnzbd downloading... but that's just the tip of the iceburg.  The real power of sabnzbd comes into play when you pair it with other services.

Introduction to Sick Beard

As aforementioned, once you have sabnzbd running, you are pretty much good to go.  The caveat is that you will need to manually find NZB files to send sabnzbd, which is pretty inconvenient unless you already know what you want to download.  Sick Beard is basically the Usenet/Sabnzbd counterpart to a DVR, and like sabnzbd, it runs on Python, and comes with a web interface you access via browser (http://localhost:8081).  With Sick Beard, you simply enter a list of shows you would like to watch (either currently airing, or off the air) and it will automatically search for new episodes and send them to sabnzbd when found.  As you can see in the screenshot above, The series "FlashForward" and "Testees" are both ended (series was cancelled), however Sick Beard was able to find all of the episodes.  Likewise for "Through the Wormhole," which is still airing - all 17 episodes were found and downloaded (aka sent to sabnzbd to be downloaded).  You can also see that "Quality" can be set to either SD (standard), HD (720p, 1080p, etc.), Custom (I set custom to look for either SD or HD, and grab whatever it finds), or All (downloads anything it finds, regardless of quality).  There is also a convenient field for "Next Ep" which displays the next date an episode is expected to air.

Adding Shows to be downloaded

With a DVR, adding shows is fairly easy.  You can add a show by going into a menu and searching by name, or usually by just browsing the DVR Guide and clicking on the show.  With Sick Beard, it's just as easy.  You can either enter shows by searching (Sick Beard uses theTVDB.com for results) by name, or by searching through folders and extracting the shows from file names of  already-downloaded episodes.  This is a great feature for anyone that already has a library of tv shows that were found before using Sick Beard.

The Show page, and downloading specific episodes

Once a show is added, you can view the list of episodes and edit any show settings on the page that is created.  Here is an example for the TV show "Louie"

As you can see, all of the settings along with some meta-data (grabbed from theTVDB.com) are displayed here, along with an "Edit" button to change the download folder, show name, quality, etc.  There are also quick links to each season in the top right, along with specials.  Below all of this is the list of actual episodes.  Here is a cropped screenshot of the Season 2 list:

Again - Sick Beard takes the list of shows you have entered, and searches for any episodes marked as "unaired" or "wanted".  When the NZB file for an episode is found, it sends it to Sabnzbd and updates the status to "snatched."  Once Sabnzbd successfully repairs, assembles, and extracts the file, Sick Beard then gets a message to update the status again to "Downloaded."  The search button on the right of each episode is a quick way to download a specific one.  We'll move on now, since this isn't a Sick Beard tutorial, just a quick overview to give you an idea of what it does.

Introduction to CouchPotato

No DVR is complete if it can only download TV shows - there are also movies, documentaries, straight-to-video releases, and more.  The counterpart to Sick Beard (which keeps track of TV shows) is CouchPotato (which keeps track of movies/documentaries).  As with both sabnzbd and Sick Beard, CouchPotato is a python script which comes with a web-interface you can access via browser.

Adding movies to the list is very easy, along with selecting the preferred quality.  CouchPotato uses a few sources including IMDB and theMovieDB for meta-data like release date, descriptions, ratings, poster, etc.  It checks for new releases every 12 hours (configurable) and when an NZB file is found, it gets sent off to sabnzbd for the heavy lifting.

Introduction to Headphones

Headphones has a very similar layout to CouchPotato, and serves the same purpose, but for music.  You can enter the name or an artist, or a particular album you want - and it will periodically search for an NZB, and send it to sabnzbd if found.  Headphones is fairly new, and development is still in progress.  There are a few features that are not fully implemented, and the entire process / configuration isn't the easiest to figure out without a little bit of tweaking.  Also, moreso than video libraries, music libraries are notoriously difficult to organize, since there are so many variations of albums, and sources for music.  Not to mention the tagging and file naming conventions are all over the place.  For those reasons, Headphones freaks out a little bit when you try to import an existing library.  I assume that with time, this will become more polished.

Other Automated Downloading Solutions

So far all of these solutions have been centered around sabnzbd (and usenet) being the sole provider of media.  There are of course many other ways to automate the searching/downloading process.  I won't go into too much detail down these other routes, but I would highly recommend:

For downloading torrents,  uTorrent (as of version 3.0) supports remote access, RSS feeds and a long list of other options.  It can also be setup to use a web interface, just like sabnzbd, Sick Beard, and couchpotato.

For downloading directly (web links, ftp, file-hosting sites like rapidshare, hotfile, etc.) JDownloader is one of the best apps out there.  It supports all sorts of cool features like scheduling, remote control, auto extraction, etc.  It supports premium accounts (rapidshare, hotfile, etc.) if you have them, and if not it will take care of the waiting process, redirections, and even has an anti-captcha module which will try to automatically answer any captcha challenges.

The Home Theater part of HTPC

With all of the media downloaded, the next step is to actually play the stuff!  For watching tv/movies, the two most popular cross-OS solutions are Boxee and XBMC.  Plesk is OSX only, and Windows Media Center is for PC only.

I have used Boxee in the past, and actually prefer it as an out-of-the-box solution.  Along with having a standalone unit, Boxee is also being built directly into TVs now - nevermind, it seems as though that has been abandoned.  In addition to playing back video and audio files, Boxee has built-in support for Hulu, Netflix, Pandora, and all sorts of other video sources (youtube, reddit, etc.)  There are plenty of skins and addons to explore with the least amount of setup.  The only reason I stopped using Boxee was due to some technical issues with video playback and hardware acceleration, along with a personal dislike of the way Boxee handles/buffers streaming media.

My preferred media app is XBMC (which stands for XBox Media Center, since it was originally designed to run on the original Microsoft XBox).  Like Boxee, it runs on Windows, OSX and Linux, and is highly extendable. Sick Beard also supports updating of the XBMC library whenever a new show is downloaded.  A small feature, but very nice to have.  There is less support for other media sources (e.g. Hulu, Netflix, etc.) without third party extensions (which don't work as well as Boxee's implementation).  I currently use XBMC because it does not have the technical issues I was experiencing with Boxee, and I prefer the additional levels of customization.

Games

XBMC and Boxee both have "Launcher" apps that can launch a game from within the interface, but they all seem a bit cumbersome.  Personally, I would rather use a gaming pc for playing modern games, and if playing games on an HTPC at all, would be via emulators and roms, or perhaps a service like OnLive.  There are even specialized extensions for Boxee and XBMC to launch roms/emulators, but again they are a hassle to use.  This is where Maximus Arcade comes into play.

Introduction to Maximus Arcade

Maximus Arcade is a Windows-only program and doesn't actually play ROMs by itself.  It's a front end for all sorts of emulators for systems like NES, Genesis, Playstation, SNES, MAME, Gameboy, N64, Gamecube, ScummVM, etc.  Anyone that plays a decent amount of emulators knows that there is usually a different program for each system, and sometimes even specific settings/programs for certain roms.  This is where Maximus really shines.  You can configure which emulators launch each type of ROM, and even fine tune the settings for each.  Maximus also hooks into EmuMovies to automatically download box art, instructions, descriptions, screenshots and even video previews for your ROMs.  Navigating is extremely simple, as you can see below:

It can take quite a while to configure Maximus Arcade (it took me an entire weekend) - since you need to download each of the emulators manually, then configure them one by one in the settings.  Once it's all setup though, this program is a dream to use.  It's very easy to navigate between ROMs and systems, and the level of customization is almost limitless.  Unlike the rest of the apps mentioned so far, this is not freeware or open-source.  It's a windows-only program that has a trial download, or a paid version for around $30.

How About the Media Server?

Great, you have a machine that can download and play media exactly how you want.  As long as you are in the same room as the computer, that is.  Making all of this accessible remotely (from work, on vacation, available to friends, from mobile devices, etc.) is the next step towards perfection of the ultimate HTPC/Media Server.  First, let's cover the obvious: streaming audio and video.  As long as you setup your home network (router, workgroups, "homegroups", etc.) correctly, you should already be able to access the files on your HTPC from other computers.  Both XBMC and Boxee will allow you to stream media from the computer, so there is no further setup required for that.  However, this only works within your home network (LAN).  If you want to watch a movie or listen to music from work or on the road, unless you have a ridiculously fast connection, there's no real way to stream.

Subsonic is a great little app (windows, osx, linux) that not only handles your audio library, but will also stream video to your browser, tablet, phone, etc.  It was originally made to stream audio files (mp3, mp4, flac, wav, etc.) but has since evolved to handling just about any audio or media format.  Want to stream a 1080p MKV video to your cellphone/tablet, but your connection is only 3G?  No problem, just set quality to low (e.g. 150kbps) and hit play.  Of course, if you aren't limited by connection speed, the only limit is how much your HTPC/Media Server computer can handle.  Personally, my mini-ITX AMD Zacate that runs on less than 50W can't handle realtime video transcoding, so if that's what you want, an Intel i3 is probably the lowest you can go.  For streaming audio however, a low-power CPU is just fine.  Making media accessible to friends and family is easy with Subsonic too.  You can create accounts for different people, see what media they are playing, and chat with them on the web-based interface. Recent updates to Subsonic have also enabled sharing of songs/albums with direct links, and Last.fm audio scrobbling.

Serving Other types of Media (eBooks, Comics, PDF, etc.)

We could stop here, and most people would.  However, this is still an incomplete solution, since digital media also covers written material!  For anyone with a tablet especially, this is a great way to have an all-in-one solution.  One of the undisputed tools for organizing an eBook collection is the Calibre eBook Manager.  Not only does it organize and allow you to read/convert/export your library of epub/pdf/txt/mobi files, but it also has a built-in web-based server!

Outstanding, so now there is a way to access your eBook files, along with all sorts of meta information.  Using this in conjunction with a free service like MagicScroll will allow you to not just access, but read your books online.  Speaking of reading online, how about a similar web-based service for reading through a comic collection?

Comic Book Archive Server (CBR Server) is a great solution for making your comic collection accessible online.  It requires about 15 minutes of setup, since you need to manually download 7-zip, ImageMagick and Java.  There are also a few issues that need to be worked out (out of memory errors, missing features, etc.) as development continues.

Accessing and Controlling the HTPC Remotely

With all of these web-interfaces for accessing media (Subsonic, Calibre, CBR Server, etc.) you may still need more ways to get to other files and folders.  This is where the following utilities can help out tremendously:

TightVNC is like any other VNC software - it allows you to remotely connect to your HTPC/Media Server from another computer, phone, browser, etc.  This is helpful for all sorts of reasons, so highly recommended.  There are other flavors of VNC out there as well like RealVNC, UltraVNC, etc.  I just prefer TightVNC as I've been using it the longest.

Dropbox is one of my "must-have" tools.  There are only two kinds of people... those that use Dropbox, and those that haven't heard of it (or don't understand it).  How does it fit into this whole HTPC/Media Server setup?  Imagine for a moment you want an easier way to download .nzb or .torrent files.  Simply point your sabnzbd/torrent client to a folder inside your dropbox called "dropbox/nzbs" (or "dropbox/torrents").  Now anywhere you have Dropbox installed, you can just save a link and know that your HTPC will start downloading right away - no matter where you are.

The Hardware

Just about all of this article so far has been hardware agnostic.  No matter what your setup, you should be able to install all of the applications mentioned so far (except for maybe Maximus Arcade, which is only for Windows).  That being said, I mentioned that my personal goal was to have a mini-itx machine that could run on less than 50W, and one that costs less than $400.  Since I originally put my machine together, there are probably a few more options that have opened up.  Anyways, here is my build list ($426 total as of 9/4/2011, at the time I purchased there were a few sales, so it was under $400):

• $110 - mobo/cpu: ASRock E350M1/USB3
• $60 - case: Silverstone ML03B
• $27 - ram: Kingston 4GB (2 x 2GB) low profile
• $95 - ssd: Intel 320 40GB
• $65 - hdd: Seagate Barracuda Green 1.5TB 5900RPM
• $46 - psu: SeaSonic SS-350SFE 350W (was actually too small for the case!)
• $20 - fans: 2x ENERMAX UC-8EB 80mm Case Fan

For the OS, I installed Windows 7 x64, and did not calculate that into the cost.  You may notice I only have 1.5TB of storage, which may seem small for an HTPC/Media Server.  Personally, I delete movies/tv shows after I am done watching them - but if I wanted more space, there is enough room to add another two 3.5in drives, so adding another 4TB of space would be trivial.  I also purchased a compact power supply unit (PSU) thinking that the case needed it, however the Silverstone case was actually made for a regular size PSU.  Not really a big issue for me, since I was stuffing the unit into an entertainment unit.  It runs 24/7 inside of a small space in a wooden entertainment unit, uses around 45W, and the temperature hasn't gotten over 48C.

Optional Hardware

Nothing is more annoying, or more certain, than having to buy a few extra odds and ends to complete an HTPC setup.  Your machine may have the perfect combination of hardware and software, but there is always room for improvement.  Here are a few optional additions that can make the difference between a headache and a home theater.

Slow LAN / Buffering Issues / Streaming over WiFi

After my setup was complete, I had intermittent issues with buffering.  My network speeds were good, and the WiFi signal was decent, but not always perfect.  Turns out, the actual placement of my wireless router/modem, and the placement of the WiFi antenna on my HTPC had too many obstructions between them (walls, beams, appliances, etc.).  I almost considered running a 50ft ethernet cable across the floor (or in the ceiling) until a friend pointed me towards Powerline Ethernet, which saved the day.  Specifically, the NETGEAR Powerline AV 200 Adapter Kit ($100).

The Powerline kit basically lets you use your electrical system as an ethernet cable.  You plug one of the adapters into a power outlet next to your modem/router, and then connect it to the modem/router with an ethernet cable.  Then, anywhere else in the house you plug the other adapter into an outlet, and run an ethernet cable from the adapter into your HTPC.  Instantly, all of the buffering issues were gone.  There aren't many products out there which are truly "plug and play," but this is one of them.  No setup needed whatsoever, it just works... and after troubleshooting network issues for over a week, it was $100 well spent.

HDTV Losing Connection with HDMI (Black Screen)

This was an extremely annoying problem.  Sometimes, when I turned the TV off, or the HTPC went to sleep - the connection between the HDMI on my computer and the TV would get lost.  I would have to manually turn off the HTPC, sometimes I even needed to unplug the power and the HDMI cable before I could get the TV to communicate again.  Turns out this is actually a fairly common problem with HTPCs and certain types of TVs.  What's happening is that the TV has an EDID (Electronic Device ID) which the computer uses to identify where to send the signal.  There is some kind of a "handshake" going on during this process - and if at any time the communication between HTPC and TV is broken, it can be a hassle to get the signal back.  This is where the Gefen HDMI Detective Plus shows it's worth.  It's painful to drop another $85 on a "budget" HTPC, especially when it's close to 1/4 the cost of the whole machine.  Then again, it's hard to put a price on peace of mind.  After reading the Amazon reviews for this unit, it wasn't a very hard sell.

Mouse, Keyboard, Remote

There are lots of options for HTPC remotes out there.  Some people swear by Logitech Harmony remotes - some like Boxee remote, etc.  I already had a Windows Media Center USB remote and love it.  The backlit rubber buttons are great, and the USB receiver seems to work from anywhere in the room (which is more than I can say for a handful of other remotes I've tried).  I believe it works on RF, so it doesn't need a line-of-sight like InfraRed.  On Amazon the remote is pretty expensive, but I'm guessing that's because it's been discontinued in favor of a newer model.

As for keyboard/mouse, I almost went for a Logitech diNovo, but was scared away by the price and bad reviews.  Instead, I opted for a Logitech unifying Couch Mouse and a cheap unifying wireless keyboard.  They don't get used much, unless I'm using the HTPC as an actual computer (or for internet browsing / emailing / etc.).  When I do need to use them though, they are invaluable - since typing something out with a remote can take about 50x longer than if you have a regular keyboard close by.

So what's the real cost?

If you have been keeping track, this budget, sub-$400 HTPC has slowly gotten more and more expensive with each of these additions.  With the Powerline Ethernet adapter, HDMI detective, and remote/keyboard/mouse, the final cost will probably be closer to $600.  When I first set out to make an HTPC, I kept reading over and over to take my intended budget and double it.  Turns out, that was correct almost to the dollar (my original budget was about $350).

But Wait, That's Not All!

There are also lots of browser extensions and user-scripts made for Sabnzbd, CouchPotato, uTorrent, JDownloader, etc.  I may add some updates to this article in the future to cover those as well.  For now, this should be more than enough to inspire you to "cut the cord!"

The Corona SDK is starting to become more and more popular among developers.  In fact, my tutorial on setting up Corona for Windows development is still the most popular post on this site.  Since I've posted, lots of other great game developers have been posting about Corona, along with Jesse Warden, who seems to have been making all sorts of contributions.  In fact here is a video from Jesse Warden that is almost 2 hours long, covering the process for developing in Corona (on a Mac).  Needless to say, there is lots of momentum and excitement surrounding Corona, and I'd say with good reason.  Corona is a great solution for creating games quickly, which will work on (most) Android devices and iOS.  Even with all of the Ant or Maven scripts in the world, it doesn't seem like there has been an easier solution made for cross-platform development yet.

(image credit: John W. Iwanski aka Chicago Man)

With all of this in mind, there are still a few things about Corona (aka Ansca Mobile) that seem to be counter-intuitive/counterproductive.   This criticism isn't meant to be stated matter-of-factly, so if any of these gripes are unwarranted, please let me know in the comments.  Here is another good blog post from a Flash/Corona developer which covers some of the same issues brought up in my article.

Android Support

The marketing copy on Corona's website states (emphasis mine) "Corona is the only complete solution for developing across platforms, OS versions, and screen sizes," but that's not entirely true.  Since Corona SDK's release #591, only Android OS 2.2+ and ARMV7 devices are supported.  This means there is a long list of fairly recent Android devices which cannot run apps made with Corona (the best list I could find of ARMV6 devices was here.  It includes HTC Aria, Hero, Legend, LG Optimus, Motorola Backflip, Samsung Galaxy, ViewSonic ViewpPad, ZTE Blade/San Francisco and others).  Not a deal-breaker, but it is worth mentioning, since Ansca Mobile doesn't make this very obvious on the website.  It also seems as though there will be no intention of adding support in the future.

Also, there are a few (somewhat important) features in Corona which only work for iOS.  For example, in the notes on media.show(), it mentions anything related to the device Camera or Photo/Media library is for iOS only.  Same goes for all of the map features - iOS only.  While this probably isn't a reason to look elsewhere, it might be.  Again, it's not overly obvious that Android isn't supported.

Response from Ansca Mobile:

As far as Android goes, everyone knows it's incredibly fragmented. There's tons of different devices, tons of form factors, versions, etc. Basically, in order to continue to move the product forward (in terms of Corona + Android), we had to draw the line somewhere. Android 2.2 and Armv7 just so happens to be where that line was drawn. For developers who absolutely need support for an old version of Android and anything below the Armv7 architecture, then Corona's definitely not for those developers.

Android Performance

All devices are not created equal.  Although the hardware specs for Android devices vary greatly (compared to iOS devices) the general consensus among the Corona development community is that on average, Android performance is worse than iOS performance when using Corona.  This is even highlighted by popular third-party library developers of Particle Candy and the Lime library.  The particle candy download page explicitly states:

please keep in mind that Corona may run slower on Android devices than on iOS devices. Also, not all of the SDK's features are available on Android devices yet. Ansca is working hard, however, to further improve both, performance and feature richness on Android devices.

The developer for Lime made a similar observation on the Corona SDK forums:

The main performance issues I find, which are certainly a lot more prominent on Android, are down to how many tiles ( or other Display Objects/Groups ) are active.

Here is a thread on the forums where you can see for yourself how this can be a headache to developers, and one without any obvious solutions other than waiting for Corona to improve Android performance.

Can't Trust Simulator Performance

This might seem obvious, since your development workstation is almost certainly more powerful (by a few orders of magnitude) than your mobile device.  You would expect a 64bit machine with 8gigs of RAM to outperform your phone, but it might not be obvious where the exact threshold is.  For example, just by browsing the forums there are many developers having issues with performance discrepancies between the simulator and devices (here is just one example).  Undoubtedly, there will always be developers having issues with something or another, and that doesn't mean it's the software's fault.  However, just about everyone that has done game development has run into performance issues at one time or another, and the typical remedy is debugging and profiling.  Both of which have very limited support right now (at least for windows).

This is further highlighted by a third-party Corona SDK library called Lime, which offers lots of helper classes and features.  Unfortunately, with some implementations there are hardware-related performance issues.  What's tricky is that it's not always obvious what the exact problem is - since some games work without issues.  When that's the case, everything is fine... but if you are having issues, you may find yourself tweaking code endlessly without any clear resolution.  Code that seems like it should work just fine (and appears to do so in the simulator) might not work on your device.

Again, this could all be code or game design related, but the fact that there are many developers having similar issues (and not a whole lot of answers) makes this noteworthy.

Response from Ansca Mobile:

... the other issues you have (such as inconsistent simulator/device performance, etc), all we ask is that if you find something, to please create a test case (a small example project that sort of reproduces and isolates the bug), and then submit a bug report. The bug base is engineering's "to-do list" so to speak, so that's definitely the fastest way to get something resolved. The bug reporter is here:

http://developer.anscamobile.com/content/bug-submission

(When you log into your account on anscamobile.com, you can click the 'Report a Bug' link at the top to get back to that page at any time)

Developer Support

Since this article was originally posted, the Corona forums have been updated to allow non-verified users read-only access to forums - also, by signing up and verifying an account (no subscription needed, trial users are ok) you have full access to read and post in the support forums.  This was perhaps main topics of this post, and the issue was completely resolved within a few days.  I believe that speaks volumes about the developer support Ansca Mobile provides for it's Corona SDK users, which is vital to a thriving new language / API / developer tool.

Debugger

The debugger for Corona SDK leaves a lot to be desired.  It's basically a command-line debugger, so any debugging you do is done via typing actions  into a terminal/command prompt.  This is obviously a bit of a hassle when trying to debug, although better than nothing! (For a while, there was no debugging option for Windows).  There are often times you will just get a "run time error at Line ##," which is certainly helpful to track down where it's happening, but there's no other information given (e.g., what type of error was it?)

Lua Library Support

Corona SDK uses Lua for the scripting, then parses this into the proper formats on their servers during the build process.  This was a great idea, since Lua can be very powerful and flexible.  However, as another blogger pointed out:

Lua has a rich library of code available to it, but Corona will not work with any of the many binary libs. In our case, this lead to us having to abandon interfacing with a web service using AES encryption. In general, you are restricted to whichever advance features the development team have included and exposed. This includes OpenFeint, Flurry, and an older version of the Facebook Connect library. For Twitter or Facebook using OAuth you'll have to roll your own solution (unless I decide to share mine…).

Authorization Process

It's not unusual for software to limit the number of installations you can have across multiple machines.  Corona SDK limits you to 2 installs per license.  That means if you have a desktop and a laptop, all your installs are accounted for.  However, what if your desktop and laptop are both PC? You also need a computer running OSX to build for iOS devices, which would put you over the 2 machine limit.  Same for running a virtual OS, with a program like VirtualBox.  If you have Corona installed on your desktop, and within a VirtualBox instance, both of your licenses are used up, and you will not be able to install on any other machines or VirtualBox instances.

The only way to "deauthorize" a computer, is by selecting an option in the Corona Simulator on that computer.  Let's say you installed onto a VirtualBox instance which has since been deleted, or onto a computer which you don't have access to anymore, or one that has been reformatted.  Unfortunately, you are out of luck and the only solution is to fill out a support ticket - so that Ansca staff can manually remove authorizations.  As far as I know, there is no other way to deauthorize your machine.  As you can imagine, this has the potential to turn into a very long and frustrating process (link goes to Corona forums, in a thread where someone has this exact problem).

Long story short, you may want to plan out your development process and think carefully about how many machines or Virtual Machines you will need for development.

Limited Subdirectory Support

When working on any apps, not just games, the organization of your code and assets can be a huge factor in how efficient your development process is.  Unfortunately for Android developers, Corona does not currently support subdirectories for all of your assets, at least not in a very robust way.  That means most of your non-lua files (music, art, etc.) are all in a single folder.  This may not be a huge issue if the number of files in your project is small (less than 20), however it can become a nightmare for more complex projects.  Here is just a small example of how this limitation could get out of control.

note: This limitation was not obvious to me right away... the Corona Simulator seemed to allow subdirectories without any problems.  Issues only arise when you build the file and try to actually run on your device.

update:  Since build #619, subdirectory support is available for iOS apps, but still not Android.

Other Gripes

Honestly, there aren't too many other gripes I have about Corona.  It seems like the perfect solution when everything works according to plan, and when you only need to use the features that are supported.  If you venture into uncharted territory however, any troubleshooting or debugging could be entirely up to you.  The community is extremely helpful, as are the admins, but there does seem to be a slight element of luck/magic/voodoo surrounding performance.  Or maybe it's just a result of incomplete/insufficient documentation - either way, this small list of gripes encompasses the main issues I have noticed with Corona.  Feel free to add on if you have others, or if you have alternate solutions.

Follow up thoughts:

Another important thing to note is Ansca Mobile's quick response to community feedback.  It seems that whenever a blog/forum/etc. post is published anywhere online, Ansca Mobile staff are there to read it and provide responses within hours.  I mentioned to the staff in an email that  I haven't discovered a development community this enthusiastic since Actionscript 3 came out.  Most of the other write-ups about Corona SDK state similar things - and now that I have access, I'll be speaking with the rest of you Corona developers in the forums!  Special thanks to Hetal and Jonathan at Ansca Mobile for the feedback.  If anyone notices other mistakes/misunderstandings in this post, please let me know via email / comments!

Click here for a demo of SumFans

When you post a video to your own youtube account, there are plenty of stats to look at.  However, if your media was posted on someone else's account, it's much harder to get the same stats.   That's where this project started - as a way to easily calculate all of the views my music has gotten, regardless of what account it was posted under (or even what site it was posted to!).  After a few long nights of coding and reading through lots of APIs, I came up with SumFans (I liked "FanSum" better, but it was taken).

The final result uses a few different components:

• PHP - handles communcation with database
• mySQL - database that stores all media information, and a log of views
• JS - lots of different jQuery libraries (UI, flot, tinysort, prettyPhoto, textshadow)
• crossrider - an awesome service that allows you to create cross-browser compatible extensions.
• APIs - mostly REST calls for last.fm and YouTube (via gdata)

Creating Cross-Browser Extensions with Crossrider!

If you are familiar with greasemonkey or userscripts, then using crossrider should be pretty simple.  If you haven't heard of any of these, just think of crossrider as javascript code that runs each time you load a page.  The problem with greasemonkey scripts are that they only work (as expected) in Firefox.  The problem with userscripts in chrome, is that you can't make cross-site scripting requests (XSS).  Crossrider solves both of these problems, and better yet, it actually comes with jQuery support built in.  Crossrider is currently in beta, but if you follow their twitter feed, you can snag an invite code like I did. UPDATE: The folks at Crossrider have offered to give readers of this blog free invites! http://crossrider.com/beta?code=SUMFANS (thanks Shmueli!)

So what does crossrider have to do with any of this?  Well, we have a database that has all of the media information to track, but depending on the website that the media is hosted on (youtube, myspace, last.fm, etc.) there are different types of info that needs to be captured.  Even once we identify that information, how can we enter it into the database easily?  Take a look at the database tables being used for a better idea (youtube, myspace, and last.fm, respectively):

As you can see, all we need for YouTube are the video IDs.  For myspace and last.fm, we need the artist and track names.  Now that we know what information needs to be stored, the hard part is actually finding all of this data and manually entering it into the database.  This is where crossrider comes to save the day!  Using crossrider, I wrote a script that will detect (using regexp) if you are looking at a Youtube video, or if you are on a last.fm track page).  If so, a small button will display on the bottom right of the browser window, which allows you to add or remove the media item to/from the database.  I got the idea from a userscript written for CouchPotato (more on CouchPotato in a future post!).  Anyways, take a look at these screenshots:

The screenshots are pretty small, but if you look closely in the bottom right corner, there is a button which reads "Remove (video id) from list."  By the time you see that button show up, the crossrider extension has already connected to my site, and checked whether or not the video on that page is in the database.  When you click on the button, crossrider sends an ajax command back to my site, which in turn adds (or removes) an entry for that media item into one of the database tables you saw above.  Once I spend more time with regexp, I will add support for myspace as well.  For now, I've just been adding myspace entries manually into the database.

Getting the View Data

Great, so there's a database storing our media information, and a browser extension which makes the process much easier for YouTube and last.fm items (with myspace and others on the way).  How do we actually use this data to get the number of views for each item?  Again, the process is a little different for each website.

YouTube

Getting stats from YouTube is actually pretty easy.  I've attempted a similar project to SumFans in the past, but this was before the sweet JSON YouTube GData API was out.  Originally I was using the Zend Gdata PHP library, which was pretty cumbersome and not as easy to install on a shared host.  With the JSON API, it couldn't be much easier.

For example, this call:

http://gdata.youtube.com/feeds/api/videos/BPOqptEDLIo?v=2&alt=jsonc

Returns something like this (I've omitted some of the data that gets returned, for space):

{
   "apiVersion":"2.0",
   "data":{
      "id":"BPOqptEDLIo",
      "uploaded":"2009-08-25T10:24:42.000Z",
      "updated":"2011-05-22T04:07:57.000Z",
      "uploader":"DaFlowContinuum",
      "category":"Music",
      "title":"sound scientists - it's ova (instrumental)",
      "description":"ALBUM: sound scientists instrumentally sound (2009) This instrumental-only album was produced by Trioptic of the Sound Scientists, and features 20 beats created over the last 5 years.",
      "duration":260,
      "rating":5.0,
      "likeCount":"8",
      "ratingCount":8,
      "viewCount":11629,
      "favoriteCount":95,
      "commentCount":33
   }
}

Pretty much all of the information you could ever want from a YouTube video, right?  The bad news is that getting the views from other websites isn't as easy.

last.fm

The API for last.fm is pretty easy to use as well, with the track.getinfo call.  For some reason however, I couldn't always rely on a response when called from the client side (jQuery).  Instead, I made the same call, but on the server with PHP.  Then I used file_get_contents to return the JSON.  Not the ideal solution, but it was the only thing that I found to work consistently.  Here is a quick snippet:

$url = "http://ws.audioscrobbler.com/2.0/?method=track.getinfo&artist=$artistName&track=$trackName&format=json&api_key=$apiKeyLastFM";
        $str = file_get_contents($url);
        echo $str;

Pretty much like the gdata API, we get this response (again, some of the data has been omitted):

{
   "track":{
      "name":"Cinco",
      "url":"http:\/\/www.last.fm\/music\/Sound+Scientists\/_\/Cinco",
      "duration":"191000",
      "listeners":"226",
      "playcount":"770",
      "artist":{
         "name":"Sound Scientists",
         "mbid":"",
         "url":"http:\/\/www.last.fm\/music\/Sound+Scientists"
      },
      "album":{
         "artist":"Sound Scientists",
         "title":"Instrumentally Sound",
         "url":"http:\/\/www.last.fm\/music\/Sound+Scientists\/Instrumentally+Sound"
      }
   }
}

Myspace, iSound and other sites

As you can see, YouTube and last.fm already have an API which provides the number of views/playcounts for us.  Myspace also has an API for getting information about media items, but unfortunately, they don't consider music or videos as media - only pictures.  And it doesn't look like they intend to add support for music/video views either.  My solution for this, was to simply use jQuery selectors to parse through the contents of a myspace page, and look for the views.  Here is the exact code:

var plays = parseInt(
    $('.songInfo span:contains("Plays:")', data)
        .next()
        .html()
        .replace("," , "")
);

Pretty short and sweet, it just grabs the number of plays, removes the commas, and returns an Int.  The code for iSound is similar:

var plays = parseInt(
    $('.white-holder-list.stats span.plays', data)
        .html()
        .replace("," , "")
);

How am I actually loading the contents of these remote pages into jQuery?  Well, I just make a $.ajax call to something like ajax.php?action=getHTML&url=http://somesite.com.  Inside ajax.php I have this:

	case 'getHTML':
		die(file_get_contents($_GET['url']));
	break;

So when I make the call, the response is just the HTML of the rendered page as if it had rendered in my own browser.  This is far from the best solution, but it's very workable for now, and dealing with jQuery selectors is a trimillion times easier than using PHP to parse the DOM. UPDATE: I've recently discovered phpquery, which is actually based on jQuery! I'll have to cover that some other time.  In lieu of this discovery, the next update is most likely going to parse the DOM in PHP on the server, and only return the data needed (plays).

Displaying the View Data

After going through all of this hard work to get all of these numbers, it's time to display them in a cool way.  The current design is pretty overkill, since I'm testing out a few different ways of visualizing this information.  Here is the screenshot (and link) from above for a quick reference:

There are a few different types of information being collected.  Since the YouTube GData API returns so much useful data, it would be a shame not to make use of it.  The Total Ratings, Comments, and Favorites are only collected from YouTube.  As for the other sites, SumFans only cares about total number of views/plays/etc.  As jQuery gets responses back with the number of views for each media item, a small div is created with a thumbnail, and number of views.  The progress bar is just using the base jQuery UI.  For YouTube results, clicking on the number of views for each video will launch that video via prettyPhoto.  Then, once all of the views have been calculated, I use tinysort.js to organize the divs from most number of views to least.  Finally, to create the graph I use flot, which is another really awesome jQuery plugin which makes creating interactive graphs extremely easy.  For example, here is the actual database table for the log:

Here is the PHP and mySQL to grab that information and return it in JSON:

    case 'getViews':

        $query = "
            SELECT
                views, date, sources
            FROM
                log
            ORDER BY
                date
            ASC
        ";

        $result = mysql_query($query);
        if(!$result) die();

        $videos = array();

        while($row=mysql_fetch_assoc($result))
        {
            $videos[] = array($row['date'], $row['views'], $row['sources']);
        }

        echo json_encode($videos);
        return false;

    break;

And finally, the javascript code for creating a graph with that JSON using flot is this:

        $.getJSON('ajax.php?action=getViews', function(data){

            var lineViews = [];
            var lineSources = [];

            $.each(data, function(index, value){
                lineViews.push([mysqlTimeStampToDate(value[0]).getTime(),value[1]]);
                lineSources.push([mysqlTimeStampToDate(value[0]).getTime(),parseInt(value[2])*3000]);
            });

            var data = [{ data: lineViews, label: "Views" }];
            var plot = $.plot($('#graph').slideDown(), data);

Another feature I'm currently working on is adding interactivity to each of the nodes on the graph.  Here is what it currently looks like when you roll over any of the nodes inside of the generated flot:

Next Steps

The ultimate goal for SumFans is to be open source, so that anyone else can use this same solution for tracking media exposure across various sites.  I have lots of high-level ideas floating around, like a repository where anyone can post a regexp script for a website, and then SumFans (both the site, and the crossrider extension) will automatically display a button on that website when it detects media.  Or even a wordpress plugin, to make this even easier for non-developers.  Speaking of non-developers, perhaps a hosted service that doesn't require a developer at all, just a login.  The latter might venture into some legal gray area, so that's much farther down the road.

There are also some small issues I'm trying to resolve, other than the ones mentioned already.  For example, as soon as you install the SumFans crossrider extension, the first time you visit a last.fm or Myspace page with media on it, you will be prompted for the location of the ajax.php files to send/receive data to/from.  I'm not aware of a crossrider "options" panel, so I'm just using a standard javascript prompt command.  And apparently, IE hates that, and won't display it.  I also tried making an input form with jQuery UI, Impromptu, and Apprise.  Unfortunately the problem (in IE, of course) is that the div shows up behind the flash content on a youtube page.  The workaround will probably be to display the input as a small form on the bottom of the window, next to the "Add/Remove (video) to/from list" button.

Finally, and most importantly, I plan on adding LOTS more sites and trackers for views (e.g. Grooveshark, facebook, torrent/download sites, etc.)

Conclusion

That's pretty much how far I've gotten with SumFans.  There's quite a bit more code making everything work.  The most interesting component of all this, is probably Crossrider.  I'll be posting the script I made for that very soon, along with the PHP, mySQL, and all other code as soon as I add a little more polish.  Hope someone finds all of this of interest!  Otherwise, I'm still perfectly happy with just using it as a personal tool to keep track of who's listening to my music!

p.s. I wanted to add that this json formatter tool was beyond helpful during the entire process, and I don't imagine I could have lived without it!

package
{
	import flash.events.Event;
	import org.flixel.FlxGame;

	[SWF(width="640", height="480", backgroundColor="#000000")]
	public class MyFlxGame extends FlxGame
	{

		public function MyFlxGame()
		{
			super(320, 240, PlayState, 2);
		}

		override protected function create(FlashEvent:Event):void
		{
			super.create(FlashEvent);
			stage.removeEventListener(Event.DEACTIVATE, onFocusLost);
			stage.removeEventListener(Event.ACTIVATE, onFocus);
		}

	}

}

As you can see, this simply removes the event listeners from ever getting the message that focus was lost.  Hopefully this may help someone else out there looking to do the same thing.  It seems odd there isn't some kind of FlxG.autoPause variable to turn this on/off a little easier.

TilemapGeneratorEntity

To try and explain it simply, the TilemapGeneratorEntity basically parses an XML file for tilemap information, along with any sprites (like enemies or powerups) we've created within DAME.  It then creates a graphic to represent the tilemap, a graphic to represent the hit area to collide with, and optionally creates sprites (like enemies) and adds them to the game.  Take a look at how a new TilemapGeneratorEntity is instantiated on line 73 of TestWorld.as:

var testMap:TilemapGeneratorEntity = new TilemapGeneratorEntity(Assets.LEVEL_TEMPLATES_XML, Assets.BG_TILES, mapLayer, "level", _totalMapsWidth, 0, true, false);

As you can see, we are passing in a few different parameters to our TilemapGeneratorEntity:

• Assets.LEVEL_TEMPLATES_XML - this is the XML file that we exported from DAME.
• Assets.BG_TILES - this is the tilemap image that we used when creating the map.
• mapLayer - this is a string that represents the XML node of the tilemap/sprites (e.g. "template3")
• "level" - this is the collision type, which is basically an ID for this collision group (called "level").
• _totalMapsWidth - this is the X offset we want to create the map at (total width of all maps we've created so far).
• 0 - this is the Y offset for the tilemap.  Since we're only scrolling horizontally, this is set to 0.
• true - whether or not to parse sprites (if set to false, only the tilemap will be created, no other sprites/enemies/etc.)
• false - whether or not to recycle maps.  This tells FlashPunk whether it should use remove() or recycle() when a map goes off screen.  Theoretically using recycle() should be more efficient, but I was getting mixed results, so I set the default to false.

Ok, let's take a look at the actual TilemapGeneratorEntity class.  Some of this will be redundant from the list above, but since this is a custom class, I want to explain it in detail:

public function TilemapGeneratorEntity($xmlAsset:*= null, $tilesetAsset:*= null, $layerName:String = null, $collisionType:String = null, $x:Number = 0.0, $y:Number = 0.0, $parseSprites:Boolean = true, $recycleMaps:Boolean = true )
		{
			_xmlAsset = $xmlAsset;
			_tilesetAsset = $tilesetAsset;
			_layerName = $layerName;
			_collisionType = $collisionType;
			_x = $x;
			_y = $y;
			_parseSprites = $parseSprites;
			_recycleMaps = $recycleMaps;
		}

So the constructor function isn't doing anything other than setting a bunch of variables that we pass into the constructor.  Technically all of the class variables (anything that starts with an _underscore) should be private, but for simplicity I left them all as public.  Notice that this class is actually extending the FlashPunk Entity class.  Therefore, there are a few methods that will be called automatically for us:

added() method:

		override public function added():void
		{
			/* DEVELOPER NOTE:
			 * all of this information is done within the added() function,
			 * because using FP.world.create() requires passing the class
			 * with no paramters.  So we call a new instance with default
			 * constructor paramters, then set each variable directly
			 * from wherever FP.world.add() was called.
			*/

			// let's focus on the map layer, based on the layer name that was passed in
			var _tileLayer:XMLList = _xmlAsset.tiles.(@layer == _layerName);

As noted in the comments starting on line 56, the reason most of the code in this class is within the added() method instead of the constructor, is because FlashPunk does not allow the passing of any parameters when using FP.world.create().  So with that explained, move down to line 65 where the code actually starts.

var _tileLayer:XMLList = _xmlAsset.tiles.(@layer == _layerName);

If you remember, _xmlAsset contains a reference to Assets.LEVEL_TEMPLATES_XML, from our Assets.as file.  Let's look at that real quick:

Assets.as

		// XML Assets
		[Embed(source = '../assets/levels/level_templates.xml', mimeType="application/octet-stream")]
		public static const LEVEL_TEMPLATES:Class;

		// lets convert the asset into an XML now, so we only have to do it once
		public static const LEVEL_TEMPLATES_XML:XML = new XML(new LEVEL_TEMPLATES);

		// and while we're at it, let's get the total count of templates too
		public static const LEVEL_TEMPLATES_COUNT:Number = LEVEL_TEMPLATES_XML.tiles.length();

First, on line 39 you can see we're embedding the XML file we got from DAME using the meta-tag (more details on that here).  This means that once we build our SWF file, everything will be embedded within.  The final SWF file will be much bigger, however once it's loaded, there won't be anything else to worry about (waiting for XML, audio, images, etc. to load).

Then, on line 43 we create a static constant with the actual data from the file.  If we d0n't do this, we won't be able to load the XML since it's still being recognized as a Class object (we need it to be an XML object).  There are lots of other ways to load XML, this was just my approach.

Finally, since we've already taken the time to put all of the XML data into a constant, why not create a constant for the total number of level templates (the number of <tiles> tags in the XML file) as well?  That's what we do on line 46, creating a constant for LEVEL_TEMPLATES_COUNT.

With that explained, let's go back to the tilemap generator

TilemapGeneratorEntity.as:

			// we set width/height/etc here for convenience, but we can't rely on having
			// the information instantly, which is why mapLayerWidth() getter function
			// was created (bottom).  It would be replaced with a width() getter function.
			_width = _tileLayer.@width;
			_height = _tileLayer.@height;
			_tileWidth = _tileLayer.@tileWidth;
			_tileHeight = _tileLayer.@tileHeight;

On lines 70-71, we store the width and height of the entire Tilemap that's being generated which is being pulled from the width attribute in the <tiles> tag in our embedded XML file.  Accessing this _width variable directly isn't reliable, so a mapLayerWidth() getter function was added as mentioned in the comments.  More on that in a second.  Next, on lines 72-73, we simple store the height and width of our tiles in this tilemap (in this example, it's 32 x 32 pixels).

Now let's give all this information to FlashPunk, and setup the Tilemap and Grid classes so that they will do most of the hard work:

// Build the empty tilemap and grid
			var _tiles:Tilemap = new Tilemap(_tilesetAsset, _width, _height, _tileWidth, _tileHeight);
			var _grid:Grid = new Grid(_width, _height, _tileWidth, _tileHeight);
			mask = _grid;

When creating the new Tilemap, just pass in the image asset (Assets.BG_TILES), along with the width and height of the tilemap, along with the width and height of the tiles. Next, we create a new instance of the Grid class, which is basically a helper for doing efficient collision detection against a Tilemap.  The last line (78) in this block of code is to set the mask (for collision detection) of our TilemapGeneratorEntity to the Grid that was just created.

About half way through this class, let's keep up the pace.  Our Tilemap and Grid is setup (width, height), but there's nothing in them yet.  Let's move on to actually creating the tilemap from the XML data:

// parse the map layer xml
			for each(var tile:XML in _tileLayer.tile)
			{

				// add the tile to the tilemap
				_tiles.setTile(
					(tile.@x / _tileWidth),
					tile.@y / _tileHeight,
					_tiles.getIndex(
						tile.@tx / _tileWidth, tile.@ty / _tileHeight
					)
				);
				// add the tile to the grid for collision detection
				_grid.setTile(
					tile.@x / _tileWidth,
					tile.@y / _tileHeight
				);
			}

Lines 81-97 run a loop which parses through each tile in our map (e.g. each of the <tile> tags within the current <tiles> tag).  On line 85, we set the tile within the tilemap.  Here is an illustration to explain what the setTile() method is doing.

This is an example of a <tile> node:

<tile tx="96" ty="0" x="256" y="0"/>

Explanation of each attribute:

• tx/ty - This is the x/y position of the tile within the tileset (image asset).
• x/y - this is the position of the tile within the Tilemap we are creating.

So if our tx is 96, and ty is 0, then lines 85-91 for this tile would be:

_tiles.setTile(
					(256 / 32),
					0 / 32,
					_tiles.getIndex(
						96 / 32, 0 / 32
					)
				);

And reducing this further:

_tiles.setTile(8, 0, _tiles.getIndex(3, 0));

We're telling FlashPunk that the coordinates (8,0) within our Tilemap (which is at 256, 0 in pixels) should be represented by the graphic at (3,0), which is the fourth tile in the array (since 0 counts as the first one).  See the image below to see what's happening here.  The grid represents a small section in the top left corner of our map.  The tileset below the grid shows the first seven items in our array of tiles to select from.

Here is another illustration of how all of the XML attributes correlate to the settings in DAME, and the Tilemap we are creating.

Now that the graphics for the tilemap have been placed, we need to setup collision detection using our Grid (which was set as our Entity's mask).  You can think of the mask as a simple black and white (or transparent) image that represents our collidable "hit" area.

Since our tilemap image and mask have been created, we could technically return all of this and start our game.  However, DAME also allows the placement of sprites in maps - which don't need to be assigned to specific tiles, but rather any pixel values we want.  This is a really cool feature that the next block of code makes great use of.  Let's take it step by step, since there are a few levels of logic to consider.

Step 1 - check to see if we should even bother to parse the sprites in this instance.

			// only add sprites if flagged to do so
			if (_parseSprites)
			{

Step 2 - first we use E4X to search through the XML data for the <sprites> tag which has the layer attribute of _layerName (e.g. "template1").  Then we use a for each statement to parse through them.

				// now let's focus on any sprite layer with the same name as the map layer
				var _spriteLayer:XMLList = _xmlAsset.sprites.(@layer == _layerName);

				for each(var sprite:XML in _spriteLayer.sprite)
				{

Step 3 - check to see how many sprites we should spawn, based on the attribute spawnAmount in our XML file.  If it's undefined, the default is set to 1.

var spawnAmount:uint = (sprite.@spawnAmount == undefined) /? 1 : uint(sprite.@spawnAmount);

Step 4 - now we set a loop for creating sprites, based on our spawnAmount.

					// create the sprites
					for (var spawnCounter:uint = 0; spawnCounter < spawnAmount; spawnCounter++)
					{

Step 5 - check the XML attribute spriteClass, so see what type of sprite we should create.  If the class doesn't exist, then we just trace out an error and continue.  In testing, it would make sense to trigger an actual error here.

						// since we're referencing classes dynamically, we can't be sure they actually exist
						try
						{
							var spriteClass:Class = getDefinitionByName(String(sprite.@className)) as Class;
						} catch (err:Error)
						{
							trace(String(sprite.@className) + " class not found!");
							continue;
						}

Let's stop for just a second here, because this technique is using a method I wasn't very familiar with.

getDefinitionByName

If you are already familiar with the getDefinitionByName method, feel free to skip ahead.  This is a useful function that allows Flash to instantiate a class at run-time, which hasn't been imported in code.  To put it another way, normally if you want to use a TextField in your application, you need to call import flash.text.TextField; at the top of your code.  Using getDefinitionByName you wouldn't have to import anything - instead you could call getDefinitionByName("flash.text.TextField").  In our case, it's more like getDefinitionByName("FlyingHorse").  The reason that this is useful, is that we can just assign all of our classes in DAME, and then create the corresponding actionscript classes afterwards.

One of the gotchas of using this method, is that there needs to be a reference of some kind to all of these classes in your code somewhere.  I just added a list of them to the end of Assets.as:

		// To avoid errors from the compiler when calling getDefinitionByName
		// just list all of the classes that are not otherwise referenced in code:
		Balloon;
		Cloud;
		FlyingHorse;
		FlyingPig;
		UFO;
		Zeppelin;

NOTE: If you do not reference the classes you intend to use via getDefinitionByName somewhere in your code, you will get the following error:

[Fault] exception, information=ReferenceError: Error #1065: Variable Balloon is not defined. In this case, we tried calling getDefinitionByName("Balloon").

Back to TilemapGeneratorEntity.as:

Side-comment over, hopefully that was useful. At this point, we have decided if a sprite needs to be created, and if so, which one. Now let's actually create it, and place it within the game according to our level design in DAME.

						// by default, we're using FP.world.create(), and assuming that entities will be recycled
						// by passing false as the second paramter, we tell FlashPunk not to add the entity yet
						var spriteEntity:Entity = FP.world.create(spriteClass, false);

On line 125, we simply create our spriteClass (e.g. "FlyingHorse," Balloon," etc.) within the world using FP.world.create().  As it says in the comments, we pass false as the second parameter, which tells FlashPunk to create the sprite, but not to add it yet (same as creating a new TextField before adding it to the stage with addChild).  This allows us to place the sprite according to our XML data:

						// set the sprite position, offset by the map layer's x/y positions (this is a DAME workaround)
						if (sprite.@spawnShape == undefined)
						{
							spriteEntity.x = (Number(sprite.@x) - Number(_tileLayer.@x)) + _x;
							spriteEntity.y = (Number(sprite.@y) - Number(_tileLayer.@y)) + _y;
						}

If you remember back in part 2, I mentioned that we would also implement the shape feature of DAME, so that we could randomly spawn new objects within the area of that shape. Line 128 is where we check to see if that spawnShape has been assigned. If not, we just place the sprite according to the x and y attributes in the <sprite> node.  So that's what happens if spawnShape is undefined.  This is what happens if it has been defined:

						else
						{
							// if spawnShape was defined, use the area to generate random placement
							var spawnShape:XMLList = _xmlAsset.shapes.shape.(@guid == sprite.@spawnShape);
							var spawnMinX:Number = Number(spawnShape.@x) + Number(sprite.@width) / 2;
							var spawnMaxX:Number = Number(spawnShape.@x) + Number(spawnShape.@width) - Number(sprite.@width) / 2;
							var spawnMinY:Number = Number(spawnShape.@y) + Number(sprite.@height) / 2;
							var spawnMaxY:Number = Number(spawnShape.@y) + Number(spawnShape.@height) - Number(sprite.@height) / 2;

							spriteEntity.x = int((Math.random() * (spawnMaxX - spawnMinX + 1) + spawnMinX - int(_tileLayer.@x)) + _x);
							spriteEntity.y = int((Math.random() * (spawnMaxY - spawnMinY + 1) + spawnMinY - int(_tileLayer.@y)) + _y);
						}

First, on line 136, we find the shape that was passed in as our spawnShape.  Then, we find the bounds of the shape (left, right, top, bottom) while taking the size of the sprite into account.  Finally, on lines 142-143, we randomly place the sprite somewhere within those bounds.  And the last step in this big loop is to add the sprite to our world (since it was already created, then positioned, now we display it).

// we've already created the entity, now add it
						FP.world.add(spriteEntity);

That's the last thing that happens in each iteration of the loop that was started back on line 100. Once all of the sprites have been parsed, we're ready to create the tilemap, set the collision group, and then add the actual tilemap to the world.

			// set the graphic to the tilemap that was just created from xml
			graphic = _tiles;
			x = _x;
			y = _y;
			type = _collisionType;

			super.added();
		}

So close to the end of this class! I imagine it's been a process reading this far. There is one other function that will be called automatically by FlashPunk (the biggest hint is that this is an override function).

update()

		override public function update():void
		{
			// once the tilemap goes off camera, we discard it
			if (x < FP.camera.x - width)
			{
				if (_recycleMaps)
				{
					// recycling tells FlashPunk to re-use this entity
					// when calling FP.world.create() on the same class
					FP.world.recycle(this);
				} else {
					// removing tells FlashPunk to destroy the entity
					// this leaves it up to flash's garbage collection
					FP.world.remove(this);
				}
			}

			super.update();
		}

This function is called every frame, and simply checks to see if the position of the tilemap is off the screen. If so, we either recycle or remove the map from the world, depending on our _recycleMaps value (default is false, which uses FP.world.remove).  Last but not least, let's cover the aforementioned "getter" method.

get mapLayerWidth()

		// since we can't rely on _width property to have the information right away,
		// this getter function will retrieve the info directly from the xml asset
		public function get mapLayerWidth():int { return int(_xmlAsset.tiles.(@layer == _layerName).@width); }

This is the final code in the TilemapGeneratorEntity class. As mentioned before, we can't rely on the _width value of our TilemapGeneratorEntity to be accurate until all of this information has been parsed, so we create a helper function which checks the XML data for this value directly (again, using E4X).

Well, that concludes part 6 of this tutorial.  The next part we will cover the FlyingEntity class, which all of our enemies extend (FlyingPig, FlyingHorse, etc.).  Stay tuned!

Developing mobile apps and games for both Android and iOS (iPhone/iPad/iTouch) is not the easiest thing in the world.  For iOS, the main option is to develop in Objective-C with Xcode in OSX.  However, if you want to develop for Android, there are a few more options - although most of them still require recoding when porting to iOS.  One of the biggest options for cross-device development is the Adobe iOS Packager for Flash/Flex/AIR.  All the code can be done in Actionscript 3, and then deployed to either device (and for free!).  The downside of this, is that without serious tweaking and compromise, the framerate on games is subpar.  In time, I'm sure Adobe will smooth things out, however as it stands, it's very limiting to work with the packager.  Enter the Corona SDK:

Corona SDK is basically a Lua library that wraps both Android and iOS functions into a single API.  In this article, I will show you how to setup an environment for developing with Corona, complete with code auto-completion, basic error checking, and an example of a box2d physics app running in both the simulator and an Android device.  All in less than 2 minutes.  Haha ok, maybe not that quick, but seriously, it takes about 15 minutes to be up and running, since there are a few things you will need to download and install.  Then, the actual box2d app will be less than 10 lines of code.

Requirements

Before we start, you will need to download these four things (don't worry, they are all free).

1. Lua for Windows
2. Java SDK v6 x86 (32bit) (note: version 6, not the newest which is version 7. Here is a direct link)
3. Corona SDK
4. IntelliJ IDEA (Community Edition)
5. Corona API (by sylvanaar2)
6. (Optional) Here is the project file for this tutorial: HelloCorona.zip
7. If testing on an Android device, minimum specs are Android OS 2.2+, and ARMV7)

Installation

This is all pretty easy.  First, install Lua, Corona SDK, and IntelliJ IDEA using recommended settings (or custom, if you want to go rogue).  The Corona API you downloaded will be a .zip file.  Just extract that somewhere (e.g. c:\sdks\sylvanaar2-idlua-sdk-corona).  If you're curious, there's only three files inside this folder: api-reference.html, corona_api.doclua, and coronoa_api.lua.

Now that everything is installed, feel free to open up the Corona simulator to test out some of the provided examples:

All of these examples are stored in the Corona SDK Installation folder (e.g. C:\Program Files (x86)\Ansca\Corona SDK\Sample Code).  The main file for each project is main.lua.  Of course, this article is about developing with Corona, so let's get to it.

Setting up IntelliJ IDEA for Lua and Corona SDK

We need to enable Lua support first, so launch IntelliJ IDEA and click on File -> Settings:

When the Settings window comes up, find the Plugins option inside of the left column, and then find the Lua plugin under the Available tab on the right.  Right click on the entry, and select Install Plugin.

Great, Lua is now supported in IDEA, complete with syntax highlighting and lots of other features.  Let's start on a Corona project.  Create a new project.

Notice that Kahlua is listed, but we want to add our own.  Click on the Configure... button.  In the top left corner of the Configure SDK window, click on the plus sign, and then select Lua SDK from the menu.

Once you select Lua SDK from the menu, you will be asked to provide the location of your Lua folder.  (e.g. C:\Program Files (x86)\Lua\5.1)

Almost done.  You can see that Lua 5.1.x is now listed on the left under Kahlua.  Before we finish, let's add the Corona API we downloaded and extracted.  Click on the Add... button.

Now find the folder where you extracted the Corona API to (e.g. c:\sdks\sylvanaar2-idlua-sdk-corona).

That's it!  Click OK until you get back to the New Project window, then make sure Lua 5.1.x is selected before clicking Finish.

(Update 9/11/2011) - One more step...

To fully enable the code-completion, go back to File -> Settings:

Then find "Lua" on the list under "IDE Settings."  There is a checkbox to "Add additional completions."  Make sure you check that box and hit ok.

Now that all of that is done, we won't have to do it again!  Now you really can create a new app within a few minutes since the tedious setup is done with.  At this point, you should have your new HelloCorona project waiting for you.  Plus, you will have some great features like syntax checking and auto-complete:

Starting a new Corona SDK project

Each Corona project is made up of at least two files: config.lua and main.lua (you will have to create these yourself).  Here's a screenshot of what this project looks like (2 lua files, and 3 images).  Important Note: Notice that all of the images and scripts are in the same folder.  If you try putting your assets into subfolders, the Corona Simulator will work as expected, but when you deploy to your mobile device, the app will hang.  It took me quite a while to figure that out on my own.

config.lua:

application =
{
	content =
	{
		width = 320,
		height = 480,
		scale = "zoomEven"
	}
}

Pretty straightforward - we create an object (in Lua it's a table) for application, and inside that, another object for content settings.  The scale is set to "zoomEven" which basically scaled the content while keeping the same aspect ratio.  Here is a complete list of options for config.lua, since this is just a very basic example.  Easy, right?  So let's look at the code for implementing box2d.

main.lua:

local background = display.newImage("background.png")

local ground = display.newImage("ground.png")
ground.y = display.contentHeight - ground.height / 2

local crate = display.newImage("crate.png")
crate.x = display.contentCenterX

Line 1 both loads and displays the background image (background.png) in a single call.  It's the first thing we add to the screen, since it's the background.  Everything added now will be on top of it (higher z-index).

Line 3 adds the ground image (ground.png) and then line 4 places it at the bottom of the screen.  This "display" object we keep referring to is analogous to the stage in flash.  It also has similar properties as a flash Sprite, like width, height, etc.  Here is a complete list of the properties each display object has in Corona SDK.  Line 6 is pretty similar, except we place the crate.x at display.contentCenterX (which is the same as stage.stageWidth / 2 in Actionscript 3).

local physics = require( "physics" )
physics.start()
physics.addBody(ground, "static")
physics.addBody(crate)

On line 9, we include physics, which is Corona SDK's wrapper for box2d  (read more about it in the guide and api).  Then, on line 10 we start the physics engine, which automatically sets gravity to (0, 9.8) and updates at the frame rate Corona is set to (default is 30 fps).

Line 11 tells the physics to recognize the ground object as a physical body, and sets it to "static" which means it will be stationary.

Line 12 adds the crate as another physics body, but uses the default type of "dynamic" which means it can move.

Running the project

All of the code for this example is done!  A total of 3 images and only 9 lines of code (10 if you include config.lua, which could all be on a single line).  There is one last thing to setup before we can run our project.  We need to edit the run configuration of the project, so first click on the drop-down menu next to the run button, and select "Edit Configurations."

In the Run/Debug Configurations window that pops up, set the Lua interpreter to the Corona Simulator.exe file, otherwise you will get errors when you try to run your code through the default Lua interpreter:

Now just click on the Run button, or go to the Run -> Run (Shift + F10) menu in IntelliJ IDEA.

A command prompt will show up, letting you know that IDEA is launching your main.lua file with the Corona Simulator (using config.lua for display settings).

You will also see the Simulator show up, where you can select various phones in the menu.

Speaking of the Simulator window, now that we can see our code in action, it looks pretty good.. but how will it look on an actual Android device?  Let's find out right now!  Click on the File -> Build menu, and fill out your Package name, Target OS, and the Save to Folder.  I have mine building directly into my Dropbox folder, since I also have Dropbox installed on my Android.  This means that as soon as I'm done building, I just open Dropbox on my phone and install the .apk file.  It really couldn't be any easier.

After you click the Build button, Corona SDK will actually connect to their build servers and generate the apk there.  Once the build process is done, the .apk gets sent back, and copied to your Save to Folder.  I imagine the same process could be done for iOS eventually, but that's not a feature on the current Corona SDK roadmap.

So, that's it!  You now have IntelliJ IDEA setup for Lua and Corona development.  All you need to do is create a new project, add your assets, config.lua and main.lua files, and hit run.  Once it looks good, just build it!

Alternate Way of Launching Simulator

Update 04/24/2012 - The process outlined above makes use of the built-in launching feature of IntelliJ.  However, there is a much better solution to launch the Corona SDK simulator from within IntelliJ IDEA, which allows the output window to show line breaks.  This method makes debugging much easier, and it's the method I'm using, instead of hitting the "Run" button.  First, copy the following code, paste it into a new text file, and save the file as "CoronaLauncher.vbs"

Note: This updated section (04/24/2012) is using IntelliJ IDEA 11.1, and some of the dialogs have changed slightly.  If you are using the older IntelliJ IDEA, all of these settings are in the same places, but the buttons/checkboxes may have been rearranged.  Feel free to comment if you need help setting up.

CoronaLauncher.vbs

Note: Lines 12 and 21 should point to your Corona Simulator.exe file.  If you are running Windows 64-bit, this will probably need to be changed to C:\Program Files (x86)\Ansca\...

Set WshShell = WScript.CreateObject ("WScript.Shell")
Set colProcessList = GetObject("Winmgmts:").ExecQuery ("Select * from Win32_Process")

'Check if Corona is already running
For Each objProcess in colProcessList
If objProcess.name = "Corona Simulator.exe" then
vFound = True
End if
Next
If vFound = True then
'If Corona is already running, then switch to it and refresh
WshShell.AppActivate "C:\Program Files\Ansca\Corona SDK\Corona Simulator.exe"
WScript.Sleep 100
WshShell.SendKeys "{ESC}"
WScript.Sleep 100
WshShell.AppActivate "Corona Simulator"
WScript.Sleep 200
WshShell.SendKeys "^r"
Else
'If Corona isn't running, launch it with your main.lua
WshShell.Run """C:\Program Files\Ansca\Corona SDK\Corona Simulator.exe """ & WScript.Arguments(0)
End If

Once you've created a CoronaLauncher.vbs file with the code above, open up IntelliJ IDEA and under the File menu, select Settings.

In the settings window that comes up, find the "External Tools" section.  It will probably be empty - so click on the add button to create a new tool.

In the Edit Tool window that pops up, enter the following values.  Pay attention to the Parameters: field, and make sure you update the value so it points to where you saved the CoronaLauncher.vbs file created earlier.  Also, make sure that "Open console" is not checked.

After hitting the OK button to save, you should now see it listed to confirm you're on the right track.

Hit OK to save this change, and then open up the Settings window again.  (Note: For me, when I hit "Apply" instead of "OK" the next step couldn't be done.  So just to be safe, hit OK.)  When the Settings window comes up, scroll down to the section for "Keymap."  Under the External Tools folder, the Simulator should now be listed.  Right click on the entry, and select "Add Keyboard Shortcut"

We're almost done, I promise.  In this window select what you want the hotkey to be.  Since I'm coming from a background in Flash, I decided to use F5 to launch the simulator. (Note: You may get a message under "Conflicts" that says F5 is already in use.  Don't worry about that - just hit OK anyways.

As mentioned above, if F5 had already been assigned to a shortcut, just overwrite it by clicking Remove

That's it!  You should now be able to hit F5, and your code will launch instantly in the Simulator!  If it's still not working, make sure you have set your main folder (which contains main.lua) as the source.  You can do that by right-clicking on the project folder and selecting "Source Root" under the "Mark Directory As" option (it's the last option in the menu) as in the screenshot below.

Conclusion

I took my first stab at Lua when writing a custom DAME exporter for FlashPunk, and swore that my next stab would be with Corona SDK.  I never expected to have an IDE setup for such a smooth build process - and I really didn't expect to port over an entire flash game in a weekend.  Within 10 hours using Corona (for the first time), I had remade a game that originally took 30+ hours with Actionscript 3.  For that reason alone, I'm in love with this SDK - despite the fairly limited set of features (so far).  During this process I also had lots of help from the following places:

• Corona SDK Review by Jon Beebe
• Flash to Corona SDK Porting Guide
• Develop with Lua, Corona SDK and IDEA by Sharif H. Khan
• Launch Corona Simulator from IntelliJ by John Lindquist

How "Free" is Corona SDK?

Corona SDK is a commercial product, but free to try indefinitely - meaning you can compile to your own devices/simulators for free, but once you want to deploy into the App Store or Android Market, you need to buy a license for Corona.  The annual license is $199 for either Android or iOS, each ($349 for both).  In case you are wondering - yes, this means for iOS development you would pay $199 for Corona SDK, in addition to paying the annual license fee to Apple.

Technically, you can use Adobe AIR and the packager to deploy for both platforms - and even without the packager.  However, the performance is still an issue, and even so - using Corona SDK to develop is still a bit quicker since so many libraries have been bundled in.  It's not nearly as flexible as rolling your own API for box2d, facebook, openfeint, etc. but again it's much quicker when you just want to get right into making the game/app and not messing around with the setup process.

Step 1 - Download and Install

First, download XAMPP 1.7.1, and Netbeans (free) or PhpStorm (30-day trial)

1. Server: XAMPP (it comes with Xdebug)
2. PHP IDE: Netbeans (PHP Version) or Jetbrains PhpStorm

Step 2 - Verify that you have Xdebug

1. Look inside of c:/xampp/php/ext for a file named php_xdebug.dll.  If it's there, move on to step 3.
2. The file you downloaded from Xdebug looks something like "php_xdebug-x.x.dll."
3. Rename that to just "php_xdebug.dll."
4. Copy that file int your xampp/php/ext folder (e.g. c:/xampp/php/ext/php_xdebug.dll)

Step 3 - Edit php.ini in XAMPP

Depending on your version of XAMPP (I'm using 1.7.1l), the php.ini file you need to edit will either be in xamp/apache/bin/php.ini, or xamp/php/php.ini.  If you have a php.ini file in both locations, edit the one in apache/bin.

1. Open the php.ini file, and search for "[Zend]."  Comment out anything in that entire column (specifically zend_extension_ts, zend_extension_manager and zend_optimizer)
2. Now search for "[XDebug]" in the file.  If it doesn't exist, create it yourself.  Then add these lines to it:

[XDebug]
zend_extension_ts="c:\xampp\php\ext\php_xdebug.dll"
xdebug.remote_enable=true

You should have a section of your php.ini file that looks something like this:

[Zend]
;zend_extension_ts = "c:\xampp\php\zendOptimizer\lib\ZendExtensionManager.dll"
;zend_extension_manager.optimizer_ts = "c:\xampp\php\zendOptimizer\lib\Optimizer"
;zend_optimizer.enable_loader = 0
;zend_optimizer.optimization_level=15
;zend_optimizer.license_path =
; Local Variables:
; tab-width: 4
; End:

[XDebug]
;; Only Zend OR (!) XDebug
zend_extension_ts="c:\xampp\php\ext\php_xdebug.dll"
xdebug.remote_enable=true

Step 4 - Restart / Start Apache, and Verify Xdebug

Now that you have Xdebug installed, restart apache from the XAMPP control panel and verify that Xdebug is configured correctly.  First, Verify PHP is working properly.  Create a php file inside of XAMPP/htdocs (e.g. XAMPP/htdocs/index.php) that just contains:

<? phpinfo(); ?>

Now open up http://localhost/index.php in a browser, and you should see something that looks like this:

Copy everything on that page (not the source-code, but the actual text on the page), and paste it into the form here: http://xdebug.org/find-binary.php

If Xdebug is installed correctly, you will see a confirmation page, otherwise you will have some error messages along with suggestions for fixing them.

Step 5 - Setup your PHP IDE for debugging with Xdebug

Now that you have Xdebug installed and running in apache (via XAMPP) let's setup your IDE.

Netbeans

As you can notice, I'm using version 6.9.1 instead of the new 7.0, because there are a few features that aren't working yet in 7.0.  I mentioned at the beginning of this post that I actually prefer Jetbrains PhpStorm 2.0.  That being said, I figured I should cover setting up Netbeans, since it's free.

First, just create a new PHP Application Project:

Now, enter a project name ("HelloXdebug") and set the source folder to a subfolder within XAMPP\htdocs (e.g. c:\xampp\htdocs\HelloXdebug). Then click Next.

After clicking Next, you will be on Step 3.  Change "Run As:" to "Script (run in command line).

Then, click on the Configure button next to PHP Interpreter.  This is where we need to set the location of php.exe.

After clicking the Configure button, a new window will pop up.  Just click the Browse button and navigate to XAMPP\php\php.exe

And just below that, are some check boxes for "Stop at First Line" and "Watches and Balloon Information."  Personally, I would just check the latter of the two, and not the first one.  You may get a warning saying that Xdebug can cause problems with Watches/Balloon Evaluation, and you probably will have problems, but they are minor.

Now just accept all of your changes, and click Finish!

To test out the debugger, here is a very basic example script.

<?
$fruitBasket = array(
    'apple',
    'pear',
    'orange'
);

foreach($fruitBasket as $fruit)
{
    $currentFruit = $fruit;
    echo $fruit;
}

?>

We're simply creating an array called $fruitBasket, with a few strings in it.  Then, we iterate through that array, set a temporary variable for each step, and then echo out the fruit name.  This is where we will see the debugger in action.  Just click on the Debug button in the toolbar to see it work.

Jetbrains PhpStorm

PhpStorm 2.0 is my preferred IDE for working on PHP sites, because there are a few features that are a little more fleshed out, such as subversion (and git) integration, more options for debugging, and some other small comforts.  Anyways, the process is pretty similar when setting PhpStorm up with Xdebug.  First, create a new project.  We'll call it "HelloXdebugStorm."

Since it's an empty project, we need to add a PHP file.  Right-click on the project, or go into the File menu and select New > PHP File:

A window will ask you for the file name and extension.  We'll be using "index.php" for this tutorial:

Still with me?  Now just copy and paste the code from above (in the Netbeans example) into your new index.php file.  For some reason line numbers are disabled by default.  This isn't important to this tutorial, but anyways just right click in the margin of the editor to enable line numbers:

Great, let's try debugging (don't get your hopes up, we're going to get an error first).  Right click anywhere in the code, and select "Debug index.php" from the menu:

If our debugger was already setup, this would be the final step.  In our case, we're going to get an error message:

As you can see, the error says "PHP home is not specified."  Click the Fix button to correct this, and you will see the following window:

Notice the warning again, that "PHP home is not specified."  Just click the browse button ("...") and navigate to your php.exe (e.g. c:\xampp\php\php.exe).  As soon as you select php.exe, the warning will change to a confirmation of your PHP version:

Now we can debug!  Of course, without any breakpoints nothing special is going to happen.  Set a breakpoint in the code by clicking in the left margin.  You will see a breakpoint (represented by a red circle) wherever you click.  Now when you debug, the code will stop at that point.

Either right click in your code and select the "Debug index.php" option as before, or use the debug button on the toolbar:

That's it!  You should now be able to debug using either Netbeans or PhpStorm.  Chances are, following this tutorial, you should also be able to setup other IDEs, using other servers as well since all of the steps are pretty much the same.

The overall structure of the code is pretty simple.  Take a look at the following diagram, which illustrates the components used in the tutorial.

As you can see, the main class is FPDameTemplatesTutorial.as, which is the class we have set to "Always Compile" in FlashDevelop:

Let's take a look at the actual code from FPDameTemplatesTutorial.as:

package
{
	import net.flashpunk.Engine;
	import net.flashpunk.FP;

	/**
	* FlashPunk, DAME and LUA Tutorial
	*
	* @author 	Thomas Gorence
	* @see		http://producerism.com
	*
	* This tutorial was written to be followed along
	* with a series on the producerism.com/blog
	*/

	public class FPDameTemplatesTutorial extends Engine
	{

		public function FPDameTemplatesTutorial():void
		{
			// make sure this matches your compiler settings
			// you can set the numbers to almost anything
			super(800, 500);

			// this will display FPS and other info
			// comment this line to turn it off
			FP.console.enable();
		}

		override public function init():void
		{
			trace("FlashPunk has initialized");
			FP.world = new TestWorld();
			super.init();
		}

	}
}

Not including any of the imports, class definitions, or comments, there's really only 4 lines of code here that are doing anything.  First of all, we only need to import 2 classes from FlashPunk: the Engine, and the global helper class, FP.

	import net.flashpunk.Engine;
	import net.flashpunk.FP;

Engine is just a very specialized MovieClip, which handles lots of game-related functions like maintaining the frame rate, reacting to items being added to the stage, and basically anything time-related.  For the most part, you won't ever need to set your own Timers or ENTER_FRAME listeners.  All of that happens within this Engine class (automatically).

FP is a class with all static functions (meaning you can access them without creating an "FP" object).  It's your go-to class for getting and setting global information like the camera, frame rate and screen size, along with lots of utility functions for checking collisions, sorting objects, loading, etc.

The constructor function within our main class (FPDameTemplatesTutorial.as) does two things:

		public function FPDameTemplatesTutorial():void
		{
			// make sure this matches your compiler settings
			// you can set the numbers to almost anything
			super(800, 500);

			// this will display FPS and other info
			// comment this line to turn it off
			FP.console.enable();
		}

On line 23, we use super() to call the constructor function of the class we've extended (net.flashpunk.Engine). Here's a peak at what Engine is looking for (Engine.as):

public function Engine(width:uint, height:uint, frameRate:Number = 60, fixed:Boolean = false)

Since it's looking for width, height, frameRate and fixed (whether or not to set a fixed frame rate), we need to pass in at least the width and the height. So that's exactly what we do on line 23. Then on line 27, we enable the FlashPunk debugging console, which is extremely helpful in development.

After the constructor function has run, and once FlashPunk has initialized, it will fire the init() function in our FPDameTemplatesTutorial.as:

		override public function init():void
		{
			trace("FlashPunk has initialized");
			FP.world = new TestWorld();
			super.init();
		}

This is an override function, meaning that it's already part of the Engine class we extended, so it's being called on it's own. However, if we want to add some custom functions we need to write our own init() before letting the Engine run it's own code, called on line 34 with super.init(). On line 33, we set the global world variable by using the FP helper class. By setting the world, we are telling FlashPunk to load our TestWorld() class. FP.world is basically the current screen/state/level. For example, splash screens, menu screens, different levels, top score screens, these are all "worlds" in FlashPunk terms. I believe in Flixel they are called states. Then, when we call super.init(), our game actually starts.

TestWorld

The only custom class we referenced in the main class above was TestWorld.as:

public class TestWorld extends World
	{

		// since the maps in DAME can be of different widths, we need
		// a way to keep track of the total length of the level we generate
		private var _totalMapsWidth:Number = 0.0;

		// create a variable for the player, to use in the update() function
		private var _player:Entity;

		public function TestWorld()
		{
			trace("TestWorld Constructor");
			super();
		}

This is essentially the code which drives the entire game, by adding the background, player, and level items (tiles and enemies) which we created in DAME. To keep things simple, we've only created two private variables for this World on lines 22 and 25.
_totalMapsWidth is just a number to keep track of the entire length of the level generated. Remember that this project will create an infinitely long level, and to make use of the FlashPunk camera system, we need to keep track of the total offset. The other variable, _player, is self-explanatory; it just holds a reference to the player's character, so it can be referenced in the update() function.

Just like the override init() function from the FPDameTemplatesTutorial class (which extended the FlashPunk Engine class), our TestWorld() extends the World class. In this case we want to override two functions, begin() and update(). Let's look at begin():

		override public function begin():void
		{

			// add the background first, so that it's on the bottom be default
			add(new BackgroundEntity);

			// add the player, and set depth to make sure they are always on top
			_player = add(new Zeppelin);
			_player.layer = -1;

			// generate maps until they fill the entire screen
			while (_totalMapsWidth < FP.stage.width + FP.camera.x)
			{
				spawnMap();
			}

			super.begin();
		}

As you can guess, the begin() function runs when our World has been set to be the active FP.world. On line 37, we add our BackgroundEntity (this is the scrolling background image for a parallax effect). Then on line 40, we create our _player, using a Zeppelin class, and set the layer to -1, which makes sure it will always be on top (the lower the number, the higher the entity will be in the depth-sorting).
On lines 44-47, we just have a loop that will create maps until the screen is totally full. As you can see, we're checking whether our _totalMapsWidth is smaller than the with of the stage plus the x position of our camera - and if it's smaller, we just spawn another map and check again.

The update() function is pretty similar:

		override public function update():void
		{
			// just have the camera follow the player
			FP.camera.x = _player.x - 50;

			// generate maps until they fill the entire screen
			while (_totalMapsWidth < FP.stage.width + FP.camera.x)
			{
				spawnMap();
			}

			super.update();
		}

On line 55, we simply make sure the camera is always 50 pixels behind our _player. This means we really only have to move our player around in code, and the camera will make sure everything else (backgrounds, objects, enemies, maps) pass by automatically. As before we simply call spawnMap() to generate a new map (based on the DAME templates) until the screen is full (lines 58-61).

We've already added the background and the _player to our screen, so lets look at the last function, spawnMap(), which takes care of everything else:

		private function spawnMap():void
		{
			// generate a random number, based on the total map layers in XML exported from DAME
			var randomMapNumber:Number = Math.ceil(Math.random() * Assets.LEVEL_TEMPLATES_COUNT);
			var mapLayer:String = "template" + randomMapNumber;

			// notice we are using add() and not create(), which is why we're also setting recycleMaps to false
			var testMap:TilemapGeneratorEntity = new TilemapGeneratorEntity(Assets.LEVEL_TEMPLATES_XML, Assets.BG_TILES, mapLayer, "level", _totalMapsWidth, 0, true, false);
			add(testMap);

			// update the total length of the generated level so far, so we know where to place the next map
			_totalMapsWidth += testMap.mapLayerWidth;
		}

First, we grab a random number between 1 and the total number of maps (<tiles> nodes) in our exported XML file (line 69). I've actually stored the number of maps in a constant variable called Assets.LEVEL_TEMPLATES_COUNT, which I'll go into later. Then we just create a string for the name of the random template (e.g. "template4" will refer to "template4" in our DAME project). Next, we generate the tilemap using a custom class, TilemapGeneratorEntity (line 73) and then add it to the world (line 74). Finally, we update the _totalMapsWidth, to keep track of how wide our world is after adding the newly generated map.

BackgroundEntity

Within our TestWorld class that we just covered, we really only added three entities (any object added to a World in FlashPunk is called an Entity).  The first of those entities was called BackgroundEntity.as. Since all of the code within this class is in the constructor function, let's just look at that:

		public function BackgroundEntity()
		{
			// create tilemap
			var _tiles:Tilemap = new Tilemap(Assets.BG_TILES, 32, 32, 32, 32);
			_tiles.setTile(0, 0, 7);

			// crate bitmapdata from tilemap
			var _bitmapData:BitmapData = new BitmapData(_tiles.width, _tiles.height, true, 0x00ffffff);
			_tiles.render(_bitmapData, new Point(0, 0), FP.camera.clone());

			// create a backdrop from bitmapdata (seamless tile background)
			var _backdrop:Backdrop = new Backdrop(_bitmapData);
			_backdrop.scrollX = _backdrop.scrollY = .5;

			// set the graphic to the backdrop
			graphic = _backdrop;
		}

First, we create a FlashPunk Tilemap, which is a class that acts as a canvas to quickly draw tiles on. When creating the Tilemap, we pass in the actual tile images (bgtiles.png), followed by the width/height of the entire tilemap, followed by the width/height of each tile. In this tutorial, our tilemap is the same size as one tile (32px by 32px), because we will just repeat that single tile as the background. If we wanted a more detailed background, we could create a much bigger tilemap. Then, since our bgtiles.png file actually has 10 32x32 pixels in it, we want to select the 8th tile (index of 7, since all arrays start at 0!) on line 26.

Now that we've created a Tilemap (which is really just a single tile right now), we want to repeat that map (again, just a single tile for this tutorial) seamlessly, and add a parallax scrolling effect to it. Luckily, there is a Backdrop class included with FlashPunk which serves this exact purpose. Since it requires a BitmapData instead of a Tilemap, we create the bitmap data on lines 29-30. We simply create a BitmapData object that is 32px by 32px, then use the _tiles.render() function (inherited from FP.graphics.Canvas) to draw the tilemap into _bitmapData.

That may seem like a convoluted way to create a Backdrop from a Tilemap in FlashPunk - and it probably is. However, I couldn't find a better way to do this, even with help from the FlashPunk IRC channel, forum and other tutorials. If you know of a better way, please let me know! Anyways, now that we have a _bitmapData, we can finally pass that into a very anti-climactic Backdrop object on line 33. Then, to add the nifty scrolling effect we simply set the _backdrop.scrollX and scrollY to 0.5, which means the background will scroll at half the rate of our camera (e.g. if our map scrolls 10px, our background will only scroll 5px).

Finally, we set the graphic of our Entity (BackgroundEntity) to the _backdrop that we went through all this trouble creating. Now when it's added to the TestWorld, it will simply show up on the screen, and will automatically scroll with the parallax effect when the camera moves.

Zeppelin

Still with me? Good. Let's take a look at our _player, which uses the Zeppelin class. Again to make it easier to follow along, we'll just look at the main functions and ignore all of the imports.
We only have two private variables for this class:

		// setting an upward force to pull Zeppelin up
		private static const GRAVITY:Number = -35.0;

		// how fast Zeppelin moves up/down and forward
		private var _speed:Number = 200.0;

Unlike most games, we've set our GRAVITY to be negative in this tutorial. The reason is because our Zeppelin will always be rising up into the air (at a rate of -35 pixels), and the player will need to push the Zeppelin back down. We also set the _speed of our Zeppelin, which is how fast it moves up and down when the player uses the arrow keys to control it.

Our Zeppelin constructor function is pretty simple:

		public function Zeppelin()
		{
			x = 20;
			y = 50;
			mask = new Pixelmask(Assets.ZEPPELIN_SPRITE);
			graphic = new Image(Assets.ZEPPELIN_SPRITE);
			type = "player";
		}

The x and y coordinates are set so that the Zeppelin is at the top left of the screen when we start. Then, we create a mask for pixel-perfect collisions using the Pixelmask class (another awesome feature of FlashPunk). With the mask set, we just assign the same image we used for the mask, to the graphic of the Zeppelin Entity (remember, when dealing with FlashPunk Entities, the "graphic" is what gets drawn to the screen).

The only remaining function in this Zeppelin class is what makes the Zeppelin move, update():

override public function update():void
		{

			var xPos:Number = x;
			var yPos:Number = y;

			// apply gravity
			yPos += GRAVITY * FP.elapsed;

Right away, we store the current position of our Zeppelin into xPos and yPos. Remember, this is an override function (line 38), so FlashPunk is calling this (Zeppelin.update()) for us every frame, while the game is game is running. We want to move our Zeppelin in sync with the camera and other entities, so we multiply any offsets by FP.elapsed. This was hard to grasp at first, but easy to think of it this way: The default FPS for the FlashPunk Engine class is 60, so instead of GRAVITY pushing our Zeppelin up by -35px each second, we're actually pushing our Zeppelin up by GRAVITY/FPS (-35/60), each time the update() function gets called.

With that out of the way, lets look at the rest of our Zeppelin:

// forward movement
			xPos += _speed * FP.elapsed;

			// Input checking
			if (Input.check(Key.UP))
			{
				// move up
				yPos -= _speed * FP.elapsed;
			} else if (Input.check(Key.DOWN))
			{
				// move down
				yPos += _speed * FP.elapsed;
			}

			// finally, set the Zeppelin's position (within limits!)
			y = Math.min(FP.stage.height-height,Math.max(0,yPos));
			x = xPos;

			super.update();
		}

Notice that our Zeppelin already has an inherent speed, so the first thing we to to the x position (xPos), is apply that forward speed. Next, we use the Input helper class to check for button presses. Then, before calling super.update(), we set the position of the actual Zeppelin. I'm using Math.min() and Math.max() (line 62) to ensure the Zeppelin never goes off the screen on the y axis, but there are lots of other ways to do this.

We've covered the main Engine class of FlashPunk (FPDameTemplatesTutorial.as), the World class (TestWorld.as), the BackgroundEntity.as, which is our scrolling background with the parallax effect, and even our Zeppelin class (Entity), which the player controls.

Of course, so far none of this code has touched on where our DAME templates come into the picture, which is all handled in the TilemapGeneratorEntity.as class. It's a good time to take a break, so that's the first thing we'll cover in the next part to this tutorial series.

Continue to Part 6

Since I'm still brand new to Lua, I won't go into the language itself, since the syntax is very similar to ActionScript.  What is important to read over though, are the DAME functions to make use of within the Lua scripts.  These custom functions are what makes everything happen, and I spent a few hours reading over the complete list of them in creating this exporter.

First of all, you will need to copy both of the Lua files in this project (FPDameTemplatesTutorial.lua and FPDameTemplatesTutorial_settings.lua) into the lua/Exporters folder within the DAME installation directory (mine was C:\Program Files\DAME\lua\Exporters).

The settings file (FPDameTemplatesTutorial_settings.lua) is only used for displaying a description and additional options within the DAME export window. For a reference, this is what the export window will look like when using the FPDameTemplatesTutorial_settings.lua file:

Here is the code for FPDameTemplatesTutorial_settings.lua:

-- Display the settings for the exporter.
DAME.AddHtmlTextLabel("An XML exporter made by T (producerism.com) for the FPDameTemplatesTutorial... tutorial.")
DAME.AddTextInput("Relative Export Path", "", "RelativeExportPath", true, "The path (relative to the .dam project file) to export the xml." )
DAME.AddTextInput("Level Name", "", "LevelName", true, "The name you wish to call this level." )
return 1

You can see that only 3 of those lines are doing anything interesting, specifically the last two.  These are DAME functions which add additional controls to the export window.  The two fields I've added are both TextInputs.  From the second parameter you can see the names of these fields are "RelativeExportPath" and "LevelName."  Those will be made available to the main script which actually parses the tile/sprite/map information and exports a map (in our case, XML).

Here is the code for FPDameTemplatesTutorial.lua.  I decided not to show it all at once, since it will be easier to explain step by step.

Lines 1-23 define a function for initializing the exporter:

function init()
	-- Sets the number of decimal places to be displayed after any floating-point numbers in your output text
	DAME.SetFloatPrecision(0)

	-- Setup tab strings for convenience
	tab1 = "\t"
	tab2 = "\t\t"
	tab3 = "\t\t\t"
	tab4 = "\t\t\t\t"

	-- This is the string where we will store all of the text to be exported as XML
	fileText = '<level>\n'

	-- create empty arrays for map, sprite, and shape layers
	mapLayers = {}
	spriteLayers = {}
	shapeLayers = {}

	-- generate a default properties string
	propertiesString = "%%proploop%% %propname%=\"%propvalue%\"%%proploopend%%"
end

First, we set the number of decimal places to be exported (in our case, 0) using DAME.SetFloatPrecision(0). The tab1-4 variables defined just below that make the exported XML file easier to read within a text editor. The fileText variable is a string which will store all of the text to be exported as an XML file. Finally, the propertiesString is a specially formatted string which DAME will use to find all of the custom properties of any object within the DAME editor. A full explanation of these properties is explained here.

Now lets look at the parseLayers() function on lines 23-64, which accounts for most of the code in this file.

-- parse all of the layers in the DAME project, and sort them into the arrays for mapLayers, spriteLayers and shapeLayers
function parseLayers()
	local groups = DAME.GetGroups()
	local groupCount = as3.tolua(groups.length)-1
	-- parse through the groups
	for groupIndex = 0,groupCount do
		local group = groups[groupIndex]
		local groupName = string.gsub(as3.tolua(group.name), " ", "_")
		local layerCount = as3.tolua(group.children.length) - 1

		-- Go through each layer and store some tables for the different layer types.
		for layerIndex = 0,layerCount do
			local layer = group.children[layerIndex]
			local isMapLayer = as3.tolua(layer.map)~=nil
			local isSpriteLayer = as3.tolua(layer.IsSpriteLayer())
			local isShapeLayer = as3.tolua(layer.IsShapeLayer())
			local layerName = string.gsub(as3.tolua(layer.name), " ", "_")

			if isMapLayer then
				table.insert(
					mapLayers,
					{
						layer=layer,
						layerName=layerName,
						xOffset=as3.tolua(layer.map.x),
						yOffset=as3.tolua(layer.map.y),
						mapWidth=as3.tolua(layer.map.width),
						mapHeight=as3.tolua(layer.map.height),
						tileWidth=as3.tolua(layer.map.tileWidth),
						tileHeight=as3.tolua(layer.map.tileHeight),
						mapWidthInTiles=as3.tolua(layer.map.widthInTiles),
						mapHeightInTiles=as3.tolua(layer.map.heightInTiles)
					}
				)
			elseif isSpriteLayer then
				table.insert(spriteLayers,{groupName,layer,layerName})
			elseif isShapeLayer then
				table.insert(shapeLayers, {groupName,layer,layerName})
			end
		end
	end
end

In this function, we first create a variable to store all of the group layers within our DAME project, using the DAME.GetGroups() function. Remember, we created 3 groups in our project, maps, sprites and shapes. Next, we create a variable, groupCount, to store the total number of groups (which will be 3 in our case). On line 28, we begin looping through all of our groups. To make things easier to read, I've created a variable called group to store the current group layer to analyze, groupName to store the name of the group (e.g. "maps") and layerCount for the total number of layers within a group (e.g. there are 6 layers in the "maps" group).

While we are looping through all of the groups, on line 34 we loop through the layers within each group. Lines 36-38 are simply checking to see what type of layer we're currently parsing, and based on the type, we either go to line 41, 57, or 59.

If the current layer being parsed is a map layer, it's put into the mapLayers array (using table.insert), along with an object which contains all of the properties of that map (lines 44-55). If the current layer is a sprite or a shape instead, it's dealt with accordingly.

Now we can cover the only other large function to worry about, createTileMaps(). Although it spans over 30 lines of code (lines 66-103), it's all very simple.

function createTilemaps()

	-- First, format the string we want to create, using $variableName for interpolation
	local mapTextFormat = tab1 .. '<tiles layer="$layerName" x="$xOffset" y="$yOffset" width="$mapWidth" height="$mapHeight" tileWidth="$tileWidth" tileHeight="$tileHeight" widthInTiles="$mapWidthInTiles" heightInTiles="$mapHeightInTiles">\n'

	local mapText = ''

	for i in ipairs(mapLayers) do
		local map = mapLayers[i]

		-- Second, interpolate $variableName with actual values
		mapText =
			string_interpolate(
				mapTextFormat,
				{
					layerName=map.layerName,
					xOffset=map.xOffset,
					yOffset=map.yOffset,
					mapWidth=map.mapWidth,
					mapHeight=map.mapHeight,
					tileWidth=map.tileWidth,
					tileHeight=map.tileHeight,
					mapWidthInTiles=map.mapWidthInTiles,
					mapHeightInTiles=map.mapHeightInTiles
				}
			)
			..
			-- Parse through all of the subchildren
			as3.tolua(DAME.ConvertMapToText(map.layer,"","",tab2.."<tile","",""," tx=\"%tilex%\" ty=\"%tiley%\" x=\"%pxpos%\" y=\"%pypos%\"/>\n", true))
			..
			tab1
			-- Close the <tiles> tag
			.."</tiles>\n"

			fileText = fileText .. mapText
	end

end

Unfortunately, string interpolation within Lua isn't as nice as some other languages (like PHP or Perl). You can't just throw variables right into a string (e.g. "Hello $firstname $lastname!" outputs "Hello John Doe!") without writing a helper function. Or rather, without finding a decent string interpolation function online, like this one (visit the link for an example). After adding this function, we can put variables right into our string, which makes reading the much easier, as you can see on line 69.

After we've defined our string format (mapTextFormat), we just pass that string along with an object that contains all of the parameters to interpolate (lines 80-90). The dots you see on lines 92, 95, and 98 just concatenate all of this text together (into the mapText variable). It should all look fairly straightforward, with the exception of line 94, which calls DAME.ConvertMapToText().

			-- Parse through all of the subchildren
			as3.tolua(DAME.ConvertMapToText(map.layer,"","",tab2.."<tile","",""," tx=\"%tilex%\" ty=\"%tiley%\" x=\"%pxpos%\" y=\"%pypos%\"/>\n", true))

When looking at the DAME Functions list, you can see that the DAME.ConvertMapToText() function accepts parameters for mapLayer, rowPrefix, rowSuffix, columnPrefix, columnSeperator, columnSuffix, keywords, and whether or not to ignoreHiddenTiles. For this tutorial, we've omitted rowPrefix and rowSuffix, and set "<tile" to be the columnPrefix. The keywords are defined in the DAME Tilemap Keywords list.

After parsing all of the child ("<tile>") nodes, we simple close the parent ("<tiles>") tag, then continue on with the loop. Once all of the tilemaps have been looped through, we append the generated text (mapText) to our fileText variable.

It's all smooth sailing from here, seriously! Lets take a look at the createSprites() function on lines 105-112:

function createSprites()
	for i in ipairs(spriteLayers) do
		fileText = fileText..tab1.."<sprites layer=\""..as3.tolua(spriteLayers[i][2].name).."\">\n"
		local creationText = tab2.."<sprite className=\"%class%\" x=\"%xpos%\" y=\"%ypos%\" width=\"%width%\" height=\"%height%\""..propertiesString.." />\n"
		fileText = fileText..as3.tolua(DAME.CreateTextForSprites(spriteLayers[i][2],creationText,"sprite type=\"%spritename%\""))
		fileText = fileText..tab1.."</sprites>\n"
	end
end

For the createSprites() function, we just loop through all of the items in the spriteLayers array. Similar to the DAME.ConvertMapToText() function, we have a DAME.CreateTextForSprites() function which parses all of the sprites in a layer. Also, just as with DAME.ConvertMapToText(), this function allows us to pass in some DAME Keywords. The inclusion of propertiesString (line 108) makes sure that if any custom parameters had been set in DAME, we capture those too.

Almost identical to the createSprites() function, is the next function, createShapes() on lines 114-122. The only big difference between the functions for sprites and shapes, is that DAME.CreateTextForShapes() allows us to pass in a different string format for circles vs rectangles:

function createShapes()
	for i in ipairs(shapeLayers) do
		fileText = fileText..tab1.."<shapes layer=\""..as3.tolua(shapeLayers[i][2].name).."\">\n"
		local circleText = tab2.."<shape type=\"circle\" x=\"%xpos%\" y=\"%ypos%\" radius=\"%radius%\""..propertiesString.." guid=\"%guid%\" />\n"
		local rectangleText = tab2.."<shape type=\"rectangle\" x=\"%xpos%\" y=\"%ypos%\" width=\"%width%\" height=\"%height%\""..propertiesString.." guid=\"%guid%\" />\n"
		fileText = fileText..as3.tolua(DAME.CreateTextForShapes(shapeLayers[i][2],circleText,rectangleText,"shape"))
		fileText = fileText..tab1.."</shapes>\n"
	end
end

Almost done... let's just look at the finish() function on lines 124-131.

function finish()
	-- Get settings from the *_settings.lua file which accopanies this one.
	local levelName = as3.tolua(VALUE_LevelName)
	local relativeExportPath = as3.tolua(DAME.GetProjectFileLocation())..'\\'..as3.tolua(VALUE_RelativeExportPath)..'\\'

	fileText = fileText.."</level>"
	DAME.WriteFile(relativeExportPath..levelName..".xml", fileText )
end

The first two lines (126-127) to notice, are where we capture the data from the custom fields defined in the settings.lua file.  As you can see, we simply use the function as3.tolua() in order to get the data, while passing in "VALUE_" and then the defined name.  If you refer to the settings code above, you can see that since the TextInput name was "LevelName," we are retrieving that data by using as3.tolua(VALUE_LevelName).

At this point, we are pretty much done.  All of the tilemaps, sprites, and shapes have been exported to the XML string (still stored in fileText).  The very last step is to add our closing </level> tag, and then write the file using DAME.WriteFile().

Now that we've covered all of the functions, we simply need to run them all in order. There are better ways to do this, but to make the file easy to follow along with, I've just called them out one after the other (lines 137-142).

init()
parseLayers()
createTilemaps()
createSprites()
createShapes()
finish()

Notes

As mentioned at the beginning of this post, most of the magic being used is actually via a set of functions provided by DAME, which can be referenced here.  I want to emphasize that this tutorial is only using a very small number of features available with DAME.  For example, I'm not using any paths, linking, sprite rotation or a few others.  The author of DAME is very responsive, and was a huge help in the process of writing this tutorial.  I found a few bugs/missing features which were fixed/implemented very quickly (within days of notifying the author via email).  In addition to the help I got via email, this crash course on Lua for ActionScript developers article by Jesse Warden was extremely helpful.

Since originally writing this exporter script (a few months ago), Lua has actually popped up quite a few times in the context of games.  Specifically, the Corona SDK for making mobile games uses Lua, and is another great example of another reason to learn it!  If I decide to cover more Lua in future tutorials, it will probably be via Coronoa.

Anyways, in the next part of this tutorial, we will finally get into the ActionScript which ties all of this together.

Continue to Part 5

First, take a look at the XML structure we'll be using:

<level>
	<tiles layer="template4" x="1440" y="0" width="480" height="480" tileWidth="32" tileHeight="32" widthInTiles="15" heightInTiles="15" >
		<tile tx="96" ty="0" x="0" y="0"/>
	</tiles>
	<sprites layer="template4">
		<sprite className="Balloon" x="1484" y="349" width="35" height="45" points="1" />
		<sprite className="Balloon" x="1621" y="2" width="35" height="45" points="1" spawnShape="74A916C5-C96B-62BE-6540-024B6D1237CB" spawnAmount="2" color="0x00ff00" />
		<sprite className="Balloon" x="1818" y="73" width="35" height="45" points="1" />
		<sprite className="Balloon" x="1750" y="343" width="35" height="45" points="1" spawnShape="74A916C5-C96B-62BE-6540-024B6D1237CB" spawnAmount="5" />
		<sprite className="FlyingPig" x="1843" y="1" width="60" height="51" spawnShape="5E3E76E3-431E-E1E1-B26C-930B32DB8AB1" spawnAmount="5" />
		<sprite className="Balloon" x="1629" y="346" width="35" height="45" points="1" />
	</sprites>
	<shapes layer="template1">
		<shape type="rectangle" x="1663" y="286" width="191" height="159" guid="74A916C5-C96B-62BE-6540-024B6D1237CB" />
		<shape type="rectangle" x="1659" y="64" width="257" height="160" guid="5E3E76E3-431E-E1E1-B26C-930B32DB8AB1" />
	</shapes>
</level>

It looks a bit complicated, but it's really not at all.  First of all, notice that I've only included a single line for each tag.  In reality, the entire file is over 1000 lines long (don't worry, Lua does all of that for us!).   On line 1 you can see that the root node for the entire XML file is called level.  This could be called anything, usually it's just <xml> but in this case I went with something that made sense to me.

The main tags

Within that root level tag, there are only 3 other main tags:

<tiles>

<tiles layer="template4" x="1440" y="0" width="480" height="480" tileWidth="32" tileHeight="32" widthInTiles="15" heightInTiles="15" >

This contains all of the tilemap information for the level.  Each time within DAME that you click on the canvas and paint a tile (or use the tile matrix tool), it will be exported into the xml file within this tag.  More on that in a second.  Note the attributes within this tag:

• layer - this is name of the layer within DAME.  For this part of the tutorial, we will just focus on "template4" because it has tiles, sprites and shapes that we will be using to spawn entities (as they are called in FlashPunk).
• x / y - This is the x/y offset within DAME.  We won't be using this number to place the tiles, but actually the sprites.  That may be a little confusing, but it's simply because DAME editor does not let you set the same properties on a sprite or shape layer, as you can on a tilemap layer.
• width / height - The dimensions of the map in pixels.  Although this could be calculated in AS3, this is handy to have as an attribute for reading through the XML code.  It also saves us the effort of figuring it out in code.
• tileWidth / tileHeight - More obvious sounding variables (in an ongoing effort to write self-commenting code) imply that these are simply the size in pixels of the tiles used.
• widthInTiles / heightInTiles - Again, this may seem redundant since we could calculate this in code from the information already provided.  It could be helpful to have for a few reasons though, so I've included it.

<sprites>

<sprites layer="template4">

Not surprisingly, this tag contains all of the sprites within the level.  As mentioned above, the <tiles> tag actually has all of the offset information needed to position the sprites.  The <sprites> tag only has one attribute actually: layer, which is set to "template4."

<shapes>

<shapes layer="template4">

Just like the <sprites> tag, shapes gets it's offset information from the <tiles> tag with the same layer name, "template4."

The Child Tags

We're almost done covering the xml format!  Within each of the main parent tags, there are child tags.  For <tiles> there is <tile>, for <sprites> there is <sprite> and for <shapes> there is <shape>.  Let's go over each one, since this is where all the important stuff is:

<tile>

<tile tx="96" ty="0" x="0" y="0"/>

One of these tags is created each time you paint a tile within DAME.  There are only 4 attributes, which are all very straight forward:

• tx / ty - This refers to the position of the tile image used within the tileset, in pixels.  In the example above, tx is 96 (pixels), which means it's 3 tiles over (the red bricks).  Since it may be hard to explain with text alone, here is an image to give you an better idea:
  
• x / y - These are the actual coordinates of each tile, relative to the tilemap.  In the provided example, x and y are both 0, meaning that this tile will be placed in the top left corner of the tilemap.

<sprite>

<sprite className="FlyingPig" x="1843" y="1" width="60" height="51" spawnShape="5E3E76E3-431E-E1E1-B26C-930B32DB8AB1" spawnAmount="5" />

For the sprite example, let's look at this flying pig.  Out of all the different elements within the XML file, the <tiles> (plural) and <sprite> (non-plural) tags will usually have the most attributes (at least the way I've coded it).

• className - This is set within each sprite's properties inside of DAME, in the class field.  In flash we will be using this to reference classes of the same name.  In this example, it's "FlyingPig" which will correspond with FlyingPig.as in a later part to this series.
• x / y - The position of the sprite, however notice that this is not relative to the tilemap.  DAME treats all sprites as if they were positioned absolutely (forgive me using CSS terminology) instead of relatively.  This is why we will use the x attribute within the corresponding <tiles> tag, to figure out where to place the sprite within the tilemap.
• width / height - DAME allows you to resize (and even rotate) sprites within the editor.  We won't be doing that in this tutorial, however it's very helpful to know how big the sprites are before loading them into memory.  By setting these attributes, we will know exactly how big to make hitboxes, masks and etc.
• spawnShape / spawnAmount - Unlike the rest of the attributes listed so far, which are generated by default in DAME, spawnShape and spawnAmount were custom properties, created within the editor.  spawnShape refers to the GUID of a shape object within DAME (explained below in just a moment).  The spawnShape will be used to randomly place the sprite somewhere within the bounds of that shape.  The spawnAmount attribute will tell Flash how many of these sprites (in this case, Flying Pigs) to spawn within the spawn area.

<shape>

<shape type="rectangle" x="1659" y="64" width="257" height="160" guid="5E3E76E3-431E-E1E1-B26C-930B32DB8AB1" />

Finally, this is the last element to look at.  While a circle is used for example in this project, there is no code to support using circles as spawnShapes.  So let's take a look at a rectangle, which is being used as a spawnShape.

• x / y - Just like our <sprite> tag, this is an absolute position of the shape, which will use the <tiles> position to offset within the code.
• width / height - Every rectangle needs the bare minimum of requirements, and this one is no exception.
• guid - This is a value that DAME automatically calculates for all objects created within the editor.  In our example, I've decided to export the guid value for just shapes, but could have exported the guid for all elements if needed.  Notice the guid of this shape, is the guid being referenced in the spawnShape attribute from the <sprite> tag above.

For a visual example of whats going on here, let's look at this template within DAME:

The FlyingPig <sprite> in this example, is the one you see in the top right of the template.  The <shape> being used as a spawnShape for the Flying Pig, is the rectangle right below him (or her).  You can also see by the marquee, that the FlyingPig sprite is selected within the DAME editor, and there are two custom properties (on the bottom left).  This is where spawnShape and spawnAmount are defined.

Conclusion of Part 3

Phew, I wasn't sure how much detail I wanted to go into with this XML file, but turns out, I wanted quite a bit.  You should now understand how to create a level within DAME editor, and what that information will look like when it comes out of DAME.  The next step of this tutorial will be to explain exactly how all of this information is converted, using Lua (which is not an acronym).

Continue to Part 4

The last part briefly went over the level design concept, so let's go further into each "Template" before moving on.

Template 1

Each "template" in this tutorial consists of a tilemaps layer, sprites layer, and shapes layer.  The first four templates are all 15 x 15 tiles.  Since each tile is 32px wide, templates 1-4 are all 480px by 480px.  In this first image, you are seeing the tilemap, sprite and shape layers titled "template1."  As you can see, it consists of a few obstacles on the tilemap layer, four balloons and two clouds on the sprite layer, and a circle on the shape layer.  The circle will not be used, other than to show how we export it into XML via Lua.   Also, notice the settings window on the right, which reflects the 15x15 tiles in the tilemap, and the 32px by 32px size of the tiles.  The rest of the settings are either default, or calculated automatically by DAME.

Template 2

Moving on, this template consists of the tilemap layer and sprite layer named "template2."  As you can see in the settings, every thing is about the same, except for the "x" variable, which is set to 480.  This is the offset of the map.  Since the last map was 480px wide, we need to offset template2 in order to see all the templates side-by-side within DAME.  The "x unit" parameter is automatically calculated by DAME.  It's basically the same offset, but in tiles.

Template 3

If you are detecting a pattern, you may already know that this image shows the tilemap and sprite layers named "template3."  This map has a flying horse, and a UFO.  As far as DAME is concerned, these two enemy objects are just different sprite images.  Again, all of the settings are very similar to the last few screenshots, but you can see the "x" variable has increased again.  This is the third map, and since the first two maps were 480px wide each, 480 x 2 = 960.  Again, the "x unit" parameter is calculated automatically.

Template 4

This is the last 480x480 template, and again the settings are following the same pattern as the first 3.  What's different is that this template contains two different shapes.  You can see the semi-transparent rectangles on the top right and bottom right of the template.  These don't mean anything special within DAME, but within the ActionScript code, we will translate these into spawning areas.  Instead of just placing enemy sprites on the map manually, maybe we want to make sure that they appear in a random position, but within certain bounds.

There are many different ways we could link an enemy object (in this case, the flying pig) to a shape.  In fact, DAME has a cool linking feature where you can just connect two objects together - sprites, shapes and paths can all be linked to each other.  However, the getting the links to export in Lua was taking more time than I wanted, so I took a different route.  By right clicking on any sprite or shape within the DAME editor, you will get a pop-up menu with a few options.  Each object inside of DAME has a unique id, which you can copy to the clipboard by selecting the "Copy GUID" option.  In this case, I've clicked on the rectangle I want to use as a spawning area for the flying pig sprite.  Notice that the shape layer called "template1" is selected in the layers tab.  Ignore the name, as the shape layer applies to all maps - but note that in order to select shapes or sprites, the layer they are on must be selected, and you must be using the selection tool (to the right of the paintbrush, which looks like four arrows points in all directions).

Now that we've copied the GUID of the rectangle we're using as a spawning area to the clipboard, we select the sprite layer that our flying pig is on, and then select him.  On the bottom right of the DAME editor, there are options to add and remove properties.  I've simply clicked  "Add Property," then added a property called "spawnShape" and pasted in the GUID on the clipboard.  Again, this doesn't mean anything to DAME - it's up to us to export that information into an XML with Lua, and then make it happen with ActionScript.  You can also see I added a property called "spawnAmount," which I've set to 5.   This will create 5 different flying pig sprites randomly within the spawnShape area (the rectangle right below the pig).

Template 5

That last template was probably the most complicated.  These next two are simple, and used to demonstrate that the maps can be of different widths.

The settings for this layer look just like the rest.  As you can see, the "x" and "x unit" offset variables are still increasing.  The first four templates were all 480 x 480.  Since 4 x 480px = 1920px, that's what we set "x" to.  You can also see that this template is much bigger than the previous ones, with the "width" set to 47 (tiles).

Template 6

This tilemap layer is even simpler.  In fact, it doesn't have any sprites on it - and by looking at the layers panel, you will notice that I haven't even created a sprite layer called "template6."  When we get all of this into Flash, we'll just be checking for a tilemap layer, and then if there's a sprite layer to go along with it, we parse that too.  If not, we'll just move along.  More on that later.  Just take a look at the last template in this file:

Again, very simple, and the settings are similar to the previous 5.  Our last offset was 1920, but the last template was 47 tiles wide.  47 tiles x 32 pixels = 1504 pixels, and 1504 + 1920 (the offset of template 5) = 3424.  And look at that, "x unit" has gone and calculated itself for us again, how thoughtful.

Part 2 Conclusion

So in this part we went over each template within the FPDameTemplatesTutorial.dam file in detail.  In the next part we will actually export the file into XML, and cover the XML string that is generated by Lua.  Hope that this part wasn't too redundant - I just felt that having a good idea of what I had in mind when designing these maps would help as we get a bit deeper into the process.  Let me know in the comments what you think!

Continue to Part 3

Over the years, I've learned many things the hard way - programming and game design not excluded.  As with almost anything, having an idea of what your final product will be is essential... otherwise, how will you know when you are done?  I'm sure everybody is different, but for me, having some kind of measurable goal really helps keep focus.  For this tutorial, the goal isn't to make a game, but to integrate FlashPunk and DAME Editor seamlessly.  The final result will be an actionscript project with all the components needed to make a game (enemies, items, player, controls, level design, etc.), along with some great extra features like random spawning areas, and an endless random level generator (it sounds fancy because it is!).  Just to point it out now, we won't actually be going into the specifics of DAME, Lua or Flash in this part of the tutorial.  Instead, we will cover all the moving parts, and explain how they work together.  In the next parts of this tutorial I will actually explain each step, along with all the code in detail.

To get started, you will need to download two things:

1. FPDameTemplatesTutorial.zip (source, assets, DAME project, Lua scripts)
2. DAME Editor

The entire project breaks down into five specific components:

1. Artwork Assets (sprites and tiles)
2. Level Design (via DAME)
3. Lua Export Script
4. XML Level (output by DAME)
5. Flash Project

Artwork Assets

It seems that a majority of games created with FlashPunk and Flixel are tile-based, and use low-res pixel art.  The main reason for this is that most of those games are designed to a very small resolution (like 320 x 240) and then scaled up in flash (to 640 x 480).  This allows the game to run extremely fast, since flash tends to (mis)use lots of memory with loads of hi-res graphics.  This is why OGMO (and other tile editors) are such great tools for tile-based games.  Where traditional tile-editors fall short (by design, not by fault) is dealing with non-tile based objects, like sprites, paths, shapes and the ability to link objects together.  DAME handles all of that with ease.

Extract the project file you downloaded above, and navigate to the assets folder.  There you will see a folder for "sprites" and another for "tiles."  The tiles file is just a typical set of 8 different 32x32 tiles.  In the sprites folder however, are some non-tile based images, including sprite sheets - a flying pig, and a flying horse.  Also notice that none of these images are lo-res or pixel art.  In fact they all have transparent backgrounds, and complex masks (alpha mattes).

Level Design

Since we have all of the art assets we need, the next step is to design a level.  Open up DAME Editor, and load the DAME project file (FPDameTemplatesTutorial.dam).  DAME project files are essentially just XML files.  In fact, we will be opening up this project file in a text editor later, and making a small, one-time change.  But first, take a look at the different elements that make up this project.  In the layers tab on the left, there are three groups: maps, sprites and shapes.  The maps group will contain all of our tile-map layers.  In the game, these can either be used as backgrounds, or as actual levels, complete with collision detection.  The sprites group contains all of the layers which contain enemies and items.  The shapes group just has one layer, and will store shapes used for randomly spawning sprites (enemies and items).  Please notice that each sprite layer shares the name with a map layer (template1, template2, etc.).  More on this later.

If you click on the "sprites" tab (next to "Layers"), you will see a list of all sprites used in the project (see right portion of screenshot above).  Finally, the main portion of the screen is devoted to the actual level design.  I will not explain how to create maps within DAME - for that, follow this tutorial.  I assure you, it's incredibly easy - especially since we won't be making use of any advanced features in this tutorial like paths, painting, text or linking.  Once you get a good understanding of how to create maps in DAME, and what the difference is between a sprite layer and a map layer, close DAME as we will be editing the FPDameTemplatesTutorial.dam project file in the next part of this FlashPunk, DAME and Lua tutorial series.

Continue to Part 2

Well, that was the short version.  For the long version, please read on:

It's rare, but luckily a project came up which has allowed me to focus more on game development.  In the past, I've made very simple games from scratch, with the exception of one using a Flash Box2D port, which in many ways was still pretty simple. At GDC Online in October of 2010, I sat in on a talk from Ben Garney, which was a very brief overview of the PushButtonEngine for Flash.  Even though I had already seen the same information from the PBE videos on youtube, being able to ask a few questions and talk with other developers there really gave me motivation to start going through the tutorials.

After learning a bit about the engine, and really falling in love with whole composition vs inheritance approach, I still felt a little overwhelmed with the workflow.  I could follow along with most of the tutorials I found online, however it seemed that the whole XML based approach was the way to go.  With limited examples provided, it was hard to get beyond any unexpected issues that came up.  I tried Flixel again, but like all the other times I've experimented with Flixel, it seemed like overkill for getting a quick and simple game up and running, in a way that made sense to me.

Searching for further tutorials, I came across a link that mentioned creating a level with Flixel and  DAME.  The tutorial didn't ever cover Flixel, and focused mostly on a tile map editor called DAME.  Well, for a few hours I lost focus on reviewing game engines, and instead became fascinated with the amount of features, and ease of use within this DAME Editor.  I also noticed that in the various formats it exported to, besides Flixel it also supported FlashPunk.

I'd always noticed the FlashPunk logo on the bottom of Flixel's homepage, which reads:

If you are allergic to flixel for one reason or another, don’t give up! Check out ChevyRay’s library FlashPunk instead, it’s awesome!

Seeing as how I hadn't been successful with PushButtonEngine or Flixel yet, I figured there was nothing to lose by checking it out.  I followed along all the text and video tutorials on FlashPunk, followed by a few more I found on The Doglion.  I noticed that almost all of the other FlashPunk developers on the forums, and on IRC all use OGMO Editor for tile maps.  It seemed to do the trick, but after playing with DAME, it just couldn't compare in features.

After following through the OGMO and FlashPunk tutorials, I had everything working pretty quickly.  And more importantly, I felt like I understand all the pieces that were working together within the engine, since they were designed in a way very similar to my own thinking.  I tried using the FlashPunk exporter in DAME, and although it exported a few files as expected, I had no idea how to use all of the files that were generated.  So instead of moving on, I decided to first make an XML exporter to reflect the output of an OGMO map.  Being my first encounter with scripting in Lua, I did fairly well - the map I designed loaded up, just as if I had made it in OGMO.

The next step, was to try and integrate the more advanced features of DAME into a FlashPunk game.  While not complete by any means, I've managed to create a custom exporter which handles tiles, sprites, custom properties and even random spawning areas.  Features I'm still working on are paths, links, and a few other things.  That being said, I'm really excited about the workflow I've been able to achieve between FlashPunk and DAME, and decided to start a new tutorial series on the entire process, starting with DAME, then Lua, then FlashPunk.  Not sure how many parts the tutorial will be in, but probably at least 4.  Anyways, hope some of you are as excited as I am about it!   Stay tuned and subscribe to my blog to follow along!

After a bit of time using my Wacom in the Flash IDE, I recreated the sketches in vector format, and then separated them into MovieClips and Graphic symbols.

Here is an example of how I decided to organize all of the different assets for now. Notice that two of the items, Gui and gauge, have linkage properties, which is why their "Export" property isn't blank like the rest of the symbols in the library.

First, let's take a look at the code and assets in the Gui class. Here's a screenshot of the assets, and their instance names:

And now, here is the code to go along with the Gui class:

package
{
	import flash.display.MovieClip;
	import flash.events.Event;
	import flash.events.MouseEvent;
	import flash.text.TextField;

	public class Gui extends MovieClip
	{
		// Event constants
		public static const APPLE_CLICKED:String = "apple clicked";
		public static const CHEESEBURGER_CLICKED:String = "cheeseburger clicked";

		// Gui elements
		public var age_txt:TextField;
		public var weight_txt:TextField;

		public var boredomGauge:Gauge;
		public var hungerGauge:Gauge;
		public var thirstGauge:Gauge;

		public var apple:MovieClip;
		public var cheeseburger:MovieClip;

		public function Gui()
		{
			// set labels
			boredomGauge.label.text = "Boredom";
			hungerGauge.label.text = "Hunger";
			thirstGauge.label.text = "Thirst";

			// add button function to apple
			apple.addEventListener(MouseEvent.CLICK, function(evt:Event) { dispatchEvent(new Event(APPLE_CLICKED)); }, false, 0, true);
			apple.buttonMode = true;
			apple.useHandCursor = true;

			// add button function to cheeseburger
			cheeseburger.addEventListener(MouseEvent.CLICK, function(evt:Event) { dispatchEvent(new Event(CHEESEBURGER_CLICKED)); }, false, 0, true);
			cheeseburger.buttonMode = true;
			cheeseburger.useHandCursor = true;
		}

		public function update($tom:Tom):void
		{
			// update all Gui fields based on $tom variable
			age_txt.text = String($tom.age);
			weight_txt.text = String($tom.weight);
			boredomGauge.value = $tom.boredom;
			hungerGauge.value = $tom.hunger;
			thirstGauge.value = $tom.thirst;
		}

	}

}

Since it's all new, let's go through it line by line.

First, you will notice two public static constants, APPLE_CLICKED and CHEESEBURGER_CLICKED, which will serve as temporary Event descriptions. We then define our textfields, age_txt and weight_txt.

Then we define the gauges, boredomGauge, hungerGauge, and thirstGauge, which make use of another new class, Gauge.as.  Finally, we need something to click on, which interacts with our character.  For now, I've created two simple MovieClips and cleverly named them apple and cheeseburger, but  in the future I will connect these to the Food.as class.

Other than the declarations we just went over, there are only 2 functions to the Gui.as class right now, the constructor function, Gui(), and update().  The constructor function is pretty simple, we just assign labels to the gauges.  Each item which uses the Gauge.as class is basically a MovieClip with certain child item, including a textfield named label. Next, we add MouseEvent listeners to the apple and cheeseburger MovieClips, which in turn dispatch an event.  This may seem redundant, but it's one way of separating the logic in the Gui fro the game logic, which will reveal it's use as the project increases in complexity.

The remaining function, update(), is used to refresh the gui to reflect all of the current values of the passed Tom.as object.

For Part 5 we'll explore the Gauge.as class, and then see everything in action so far!

here it is in action on wonderfl

The explanation (or tutorial) part of this post will be complete soon.  I will also optimize the code in the next couple of posts.  Until then, take a look at the code and try to understand what's going on.

package
{
    import flash.display.Sprite;

    public class SlotMachine extends Sprite {

        private var _credits:uint = 4; // start with $20

        private var _slotReel1:SlotReel;
        private var _slotReel2:SlotReel;
        private var _slotReel3:SlotReel;

        public function SlotMachine()
        {   

            _slotReel1 = new SlotReel();
            _slotReel2 = new SlotReel();
            _slotReel3 = new SlotReel();

            spinReels();
            spinReels();
            spinReels();
            spinReels();
        }

        private function spinReels():void
        {
            if (_credits)
            {
                _credits--; // costs $1 per spin

                _slotReel1.spin();
                _slotReel2.spin();
                _slotReel3.spin();

                // check for matches
                if (_slotReel1.value == _slotReel2.value && _slotReel1.value == _slotReel3.value)
                {
                    trace("win!");
                    _credits += 1000;
                }
                else if (_slotReel1.value == _slotReel2.value)
                {
                    _slotReel1.hold = true;
                    _slotReel2.hold = true;
                }
                else if (_slotReel1.value == _slotReel3.value)
                {
                    _slotReel1.hold = true;
                    _slotReel3.hold = true;
                }
                else if (_slotReel2.value == _slotReel3.value)
                {
                    _slotReel2.hold = true;
                    _slotReel3.hold = true;
                }

                trace(_slotReel1.value + " " + _slotReel2.value + " " + _slotReel3.value+" credits left: "+_credits);
            } else {
                trace("out of credits!");
            }

        }

    }
}

import flash.display.MovieClip;

class SlotReel extends MovieClip {

    private var _numberOfSlotFrames:uint = 12;
    private var _currentSlotFrame:uint;
    public var hold:Boolean;

    public function SlotReel(){ super(); }

    public function spin():void
    {
        if (!hold)
        {
            _currentSlotFrame = Math.round(Math.random() * (_numberOfSlotFrames- 1) + 1);
            gotoAndStop(_currentSlotFrame);
        }
    }

    public function get value():uint { return _currentSlotFrame; }
}