Getting Started With HaxePunk
HaxePunk, is an amazing Haxe port of the Flash / AS3 game development framework, FlashPunk. HaxePunk is nearly identical to FlashPunk, but isn’t a direct 1 to 1 port. Since HaxePunk utilizes the NME library to target multiple platforms, it has slight alterations where needed, and performances optimizations strewn throughout. In this guide, I’ll get you set up with a bare-bones, ready to go HaxePunk project, which will hopefully help you get on your way to programming games using Haxe.
Step 1 – Getting Started With Haxe, NME, And FlashDevelop
In order to follow this guide, you’ll need to get your computer set up with Haxe, NME, and FlashDevelop. If you haven’t done so already, worry not, as I’ve conveniently linked to my guide in the previous sentence. Once everything from the previous guide is up and running on your computer, you’re ready to continue.
Step 2 – Installing HaxePunk
Now that you have your blank NME project, it’s time to install HaxePunk. Thanks to the HaxeLib Haxe Package Manager, it’s extremely easy to add new libraries to your project. The first step to adding a library through the HaxeLib Haxe Package Manager, is knowing which library it is you want to install. Haxe has a nice page displaying all compatible libraries, which you can view on their site. In our case, we already know that we want HaxePunk, so we can move along to actually installing said library.
To install HaxePunk, we first need to open the command prompt. Once on the command prompt, we run the following command:
You’ll then be asked which Library you’d like to install, in which case you’ll enter the obvious:
Your screen will look something like the image below. HaxePunk files will then be installed, and you’re ready to move on.
*Remember to update HaxePunk, and all of your libraries, by running the command “haxelib upgrade” from time to time.
Keep in mind that you can manually add a library by copying it to your global classpath or project directory. I occasionally do this to test the latest, unreleased version of HaxePunk, which can be found on GitHub.
Step 3 – Adding HaxePunk To Your Project
Now that HaxePunk is installed on our machine, we’ll need to know how to add it to our projects. Doing so is extremely simple, and is done through our “application.nmml” file, which can be found in the project folder’s root.
At first glance, this file is kind of overwhelming, and may not make much sense to you, but the parts we’re worried about are incredibly simple. If you look down to lines 15-17, you’ll see a section of code commented as “classpath, haxe libs”; this is where we add new libraries to our project using the Haxe Lib Haxe Package Manager. Simply type the following below the current libraries (or copy and paste, then change the library name), which should be on line 18 (line number may change with future versions of Haxe, just go below the current libraries listed).
<haxelib name="HaxePunk" />
Once you start typing HaxePunk, FlashDevelop will even help you out using auto-complete, so you can see how simple this really is. Once that line is added, make sure you save, or the changes won’t take effect. Once saved, you should notice that the library is added to the Project tab’s folder hierarchy in FlashDevelop – if it’s not there, ensure you’ve saved your “application.nmml” file, and / or reboot FlashDevelop. If everything has worked thus far, HaxePunk is now ready to be used in your project.
Ready To Go
Now that HaxePunk is ready to go, you’re now ready to use the library as you please. If you’ve used FlashPunk, you’ll feel right at home, as HaxePunk functions almost exactly the same way. If you’re unfamiliar with FlashPunk, and have no idea where to go from here, I suggest reading up on how to use FlashPunk, as there are plenty of great tutorials out there. I’ll be writing another guide in the near future on the very basics of HaxePunk, so if this guide helped you out, and you’re looking to move forward, keep an eye out for that.
San Francisco Bound – FGS, GDC, and More
March is here yet again, and it’s time for another crazy adventure to San Francisco. Last year, I brought a couple of friends along for the ride; we had a great time attending the Indie Giving event, Flash Gaming Summit, and numerous parties, as well as getting in some great outdoors time around the city. This year, I’ll be staying twice as long as I have previous years, and will return to my roots by travelling with Andrew Sandifer once more. We’re definitely going to need the extra time this year, as we’ll be hitting up Flash Game Summit, GDC, and more.
This year will be my third year attending the Indie Giving event. Previous years have been a great time, and have helped make my trip considerably more affordable through the support of the event’s generous sponsors. This year, Indie Giving has gone above and beyond – not only did everyone attending receive a pass to Flash Game Summit, but we also received an Indie Summit Pass for the Game Developers Conference. These passes were in very high demand this year, and sold out months ago. Needless to say, I’m very happy to get out their and help the San Francisco community, and even more excited to finally be attending GDC.
Flash Gaming Summit
Flash Gaming Summit is back for it’s 5th year. This will be my 3rd year attending, and I’m quite intrigued to hear what everyone has to say. As many know, the Flash Game Industry is in a strange position at the moment, and while I can’t say it’s dying, it’s definitely transforming. There’s sure to be a lot of information and opinions around the subject, and it’ll be interesting to see how conversations pan out. As always, there’s sure to be great parties, after parties, and after after parties.
Game Developers Conference
It’s a warm and cozy feeling to know that this year, I will attend a GDC party while actually holding a pass! I’ve been to a number of parties through connections, but it’s comforting to know that I’ll be going legit this year. That aside, I’m extremely excited to be attending the game developer conference this year, and I greatly look forward to meeting countless members of the industry. Flash Game Summit has been a blast thus far, but with GDC, this place about to blow.
During the month of March, I enjoy St. Patties day, followed by my birthday the next day, and then my trip to San Francisco soon after. I’ve been perfectly content with this the last few years, if not overjoyed, but things just got even better. I found out that Lindsey Stirling was holding a concert in my city this month, but it was unfortunately being held the night of the day I fly out. This was slightly upsetting, but with all the events ahead, I couldn’t be too bummed about it. Out of pure curiosity, we looked up her tour schedule, and learned that she would be in San Francisco on April 3rd. With GDC ending on the 29th, it was pretty clear what had to be done, and we extended our trip until the 4th; we will now be attending an awesome show to wrap up what’s sure to be an amazing trip.
Let’s Meet Up!
I’ll be flying out March 21st, and will be returning the night of April 4th. If you’re in San Francisco during this time, and would like to meet up, get in touch and we’ll work something out.
Getting Started With Haxe, NME, And FlashDevelop
Haxe is gaining a lot of popularity as of late, but it’s still quite the new language. That being said, it’s tricky to find proper documentation for everything you need on the internet, like you could for say AS3 or C++. I’ve heard a number of people say they tried to get Haxe running, but ran into problems, and simply couldn’t be bothered trying to figure things out. I wrote this getting started guide as idiot proof as a I possibly could (hence the 5 images for some steps), and my hope is that anyone, absolutely anyone, could follow this guide and get Haxe, NME, and FlashDevelop up and running on their machine. The guide isn’t nearly as long as it seems, and I don’t skip a single step, so you should be good to go by the end of this.
Step 1 – Downloading Haxe and NME
Before you can get started with Haxe and NME, you’ll need to download, and install them on your computer. To do this, simply head over to the NME Download Page, and select the install method that fits your machine (Windows, OSX, Linux).
*Note that Haxe and NME are two different things. We’ll be using both together, but one could install Haxe without NME. The above download contains both Haxe and NME in one download, and is our solution to cross platform magic.
Step 2 – Installing Haxe and NME
I’ve only experienced the setup on a Windows machine, but I’m quite convinced that the process is similar on all platforms.
Simply locate the file you downloaded in the previous step, and run it on your computer. Follow the very simple install instructions, and you should see the following:
Step 3 – NME Setup
Now that Haxe and NME are installed on your machine, we need to setup NME. Unfortunately, NME doesn’t have a setup application, and must be done from the command line. This is extremely simple if you have instructions though, so follow along.
Start by opening a command prompt. On Windows XP, go to Start > Run then type cmd. On Windows 7, go to start, and type in cmd under search, then press enter.
Once the command prompt is up, type the following, and press enter.
nme setup windows
You’ll be asked to install Visual Studio C++ Express, simply press “y” to everything (even if you already have it), and allow it to install. I already had it, but was asked if I wanted to download a service pack. Regardless of what you’re asked, simply say yes, and allow everything to install.
Haxe and NME are now installed on your computer.
Step 4 – Testing Your Installation
Now that Haxe is installed, we’ll quickly test a few commands to ensure the installation was successful.
In the command prompt, type the following:
If Haxe is installed properly, you should see the following optional commands:
Additionally, type in the following:
You should see the following:
If both of the above worked, great, if not, feel free to drop a comment and I’ll attempt to troubleshoot the issue with you.
*Take note of the “upgrade” command. Typing haxelib upgrade into the command prompt will automatically update all libraries you have installed, including NME, which is extremely useful for keeping up with updates.
Step 5 – Downloading FlashDevelop
Now that Haxe and NME are on our machine, we’ll need an IDE (integrated development environment) to work with. If you’re on Windows, the hands-down option is FlashDevelop. Head over to the official FlashDevelop site to download the latest version now.
On the main page you’ll see this button:
Click that button, and you’ll be taken to the download page. Scroll down the page to the download section, and click the link to begin your download.
If you’re not using Windows, or simply want to try another IDE, another popular choice is Sublime Text 2, though I won’t be covering how to get started with that, and you’ll be on your own.
Step 6 – Installing FlashDevelop
Locate the installer you downloaded in the previous step, and run it. Proceed to install everything (specifically Flex SDK, AIR SDK, and Flash Player), and create whatever shortcuts you see fit. The installation process should look as follows, and will take a few minutes due to downloading the SDKs.
*The Flex SDK and Air SDK won’t be used for Haxe, but it’s still a good idea to download them to get the most out of FlashDevelop.
Step 7 – Creating A Test Project
Now that Haxe, NME, and FlashDevelop are all installed, we can go ahead and make our first project. To do this, simply open FlashDevelop, then go to Project >New Project
You’ll then have a screen come up with a somewhat overwhelming number of options, but fear not, everything is quite straightforward. Simply navigate your eyes to the “Haxe” section (below the initial AS3 section), and select the NME Project option.
Once you’ve selected the NME Project option, proceed to the bottom of the New Project page to fill out your project information. The first field is the project name, quite self-explanatory. Next is the project location, also self-explanatory. Lastly is the package field, which I personally leave blank. On the bottom of this page, you’ll notice a check box for “Create directory for project”; if you’ve yet to create a folder for this project, check this box, otherwise, point to your pre-created directory in the location field (second field we filled out). Once everything is filled out, press OK and your project will be created.
Step 8 – Configuring Your Test Project
Before we test our project, it’s best we familiarize ourselves with how NME project information is stored, and how it varies from a typical AS3 project in FlashDevelop.
First off, close FlashDevelop, and locate your project directory on your computer. Once you’ve located your project folder, open it up, and take a look at the files in front of you. You should have the following:
The “assets” folder is simple, this is where you store your graphics, audio, fonts, etc. The “bin” folder, is where all of your final compiled projects will end. Within that folder you’ll find locations for SWF, EXE, and all other files for targets you’ve compiled to. Next is the “src” folder, this is where all of your project code goes (aside from libraries, but that’s not important right now). Next is the YourProjectName.hxproj, obviously I’m substituting the name here for whatever your project is called, but the extension .hxproj is always the same. This is the file that FlashDevelop uses to manage your project, and is the file you’ll open when you wish to work on your Haxe project in FlashDevelop. Lastly, the “nme-readme.txt” file. This is simply a hand-holding file for anyone new to NME, and I highly suggest you give it a quick read, in addition to following this guide.
Now that you know what everything is, go ahead and open the YourProject.hxproj file. This will open up FlashDevelop again, with your project files displayed on the far right, underneath the “Project” tab. Double click the application.nmml file, and stay calm as a bunch of intimidating text flies onto your screen. While all of this may or may not look completely foreign to you, it’s all quite simple. Unlike AS3 projects in FlashDevelop, project information for NME projects is stored as XML in this file; all you’re seeing here, is a bunch of information that tells FlashDevelop how to compile your project. Do no try to alter these settings by going to Project > Properties (like you would an AS3 project), as it will not work. Let’s take a look at some of this information more closely.
<window background="#000000" fps="60" />
This is simple, the first property is the background color of your project as a hex value (#000000 makes your background black, assuming you had no graphics on screen to cover it), and the second is the frames per second of your project (defaulted to 60, but personally I work with 30, so change that to 30 if you please).
<window width="800" height="480" unless="mobile" />
As you can probably gather, this is simply the width and height of your project, unless you’re targeting mobile, in which case more complex code will override this.
<!-- classpath, haxe libs --> <source path="src" /> <haxelib name="nme" />
This part is extremely important, as this is where you tell FlashDevelop where your code and additional libraries are location. As you can see, the source path is set to “src”. As we already know, this is where your project’s code will go. The next line, is telling FlashDevelop where the NME library is, which is part of haxelib. If you had additional libraries, such as HaxePunk (Getting started with Haxepunk tutorial coming soon), you’d list them here, with the same format.
Continuing on, you’ve got the path to your icon (used for EXEs and perhaps other projects, I haven’t tested this), your assets directory (and a rename rule, ignore this if you don’t understand it), as well as some technical information that I currently don’t know, or believe I don’t need to know.
Keep all the above information in mind, but most of all, just remember that this file is how you add libraries (like HaxePunk), and change your fps, project width, and project height. The rest is important, but you can look it up later if ever needed.
Step 9 – Testing Your Project
Now that we’ve created a project, it’s time to see if everything is in working order. Before we do this however, let’s set up a quick trace function to further let us know that everything is in working order.
Locate the “src” folder within FlashDevelop (under the Project tab), and press the small “+” button to expand that folder.
Double click Main.hx to open it, and take a quick look at the code. On line 27, you should notice a comment that says “entry point”. Just below this line, add the following call to the trace function, so we can further see that our project is up and running from the output panel (located at the bottom of FlashDevelop).
Lib.trace("Project is up and running");
*Note, comments are denoted by a // before them (or /* open, */ close, for multi-line comments), and are skipped by the compiler.
One last step before we compile our project, and that’s setting our target platform. To demonstrate the power of NME, we’ll start with Flash, and then target windows by making an EXE. At the top of FlashDevelop, you’ll see two drop-down menus. The left should be on “Debug”, and the right one set to “Flash”. If this isn’t the case, go ahead and change them to those values now. They should now look as follows:
Finally, it’s time to test our project. To do this, all wee need to do is go to Project > Test project; alternatively, we can press F5, or Ctrl + Enter (the latter being my personal choice).
If everything has worked, you should now have successfully compiled your first Haxe NME project, and should see an 800×600, empty black flash player window (assuming you didn’t change the hex value in the .nmml when we covered that in step 8), and the text “Project is running” in your output panel, like so:
*My window is only 512 x 448, I changed it so I could better fit this screenshot into the article.
Now let’s target Windows with an EXE, because that’s half the point of learning Haxe and NME! Go ahead and change the target platform to windows on the drop down menu, as we did with Flash.
Compile in whichever way you feel fit (Project > Test Project, F5, or Ctrl + Enter), and prepare to see your project run as an EXE. You should see the following when compiling is complete:
*The first compile may take a minute or two, as the entire NME library is compiled. Future compiles are much faster, and only take changes into consideration.
*Some antivirus software, such as Avast, will attempt to stop the execution of the EXE due to its “low reputation”, or some other reason. Simply ignore this, as all is well.
There you have it, your ability to program aside, you are now ready to start creating projects using Haxe and NME. Enjoy the cross-platform magic, increased performance where applicable (Flash Platform for sure), and bragging rights that come with using Haxe, but above all, have fun with it!
While this guide does get you up and running, I’m well aware that there are many changes between Haxe and AS3, or whatever other language you may be coming from. I will be working on some follow-up articles to this in the near future, ranging from learning the basic changes from AS3, to getting started with a HaxePunk (FlashPunk port) project. For now, feel free to ask questions in the comments below, and be sure to check out the following useful links.
AS3 Migration – A useful page on Haxe.org that covers the absolute basic changes in Haxe needed for someone coming from AS3.
Indirection – An inspirational piece that’s sure to get you excited about switching to Haxe.
lib.haxe.org - A list of libraries available through the haxelib library manager.
Pirate Pig Game Example – Joshua Granick provides us with an example NME game, source and all.
@NME – The genius behind NME. They’re quite active on Twitter, so if you have any questions, send them a tweet.
Goodbye 2012, Hello 2013
2012 has come and gone, and while it wasn’t the most productive year for me, I did get a lot done. I flew out to California to attend FlashGamingSummit 4, I participated in Ludum Dare 24 (and ranked 45th for audio out of over 1400 entries), released a game for Halloween (even though it wasn’t 100% complete), increased the number of clients I have for my game consulting service, continued to write for TutsPlus, and put a huge dent in a few serious projects of mine. All of that doesn’t amount to even half of what I would have liked to get done, but I’m not one to fret on the past, and there’s only room for improvement, so on I go into 2013.
With every new year, comes a new pile of goals. 2013 is no exception, and I’ve got plenty of personal, and work related goals lined up for the year.
Switching to Haxe
I began trying out Haxe in the final days of 2012. I absolutely loved it, and as of writing this, will be leaving AS3, and using Haxe exclusively. I’ll now be targeting multiple paltforms, and look forward to breaking away from exclusively using the Flash sponsorship model.
OneGameAMonth is all the rage in the indie world, and I fancy me some rage. For those of you unfamiliar with #OneGameAMonth, stop living under a rock. Just messing, the idea, as the name implies, is to release a game each month for an entire year. Actually finishing a game is by far the hardest part of being a developer, myself included, so I’ve jumped on board to help overcome that obstacle. If you feel like tracking my progress for whatever reason, here’s my OneGameAMonth profile.
Tower of Greed Sequel
Art by Andrew Sandifer
There, I said it, it’s in writing. This year, Tower of Greed is getting a sequel, because that’s what I want to do, it’s a passion. I made a rule about laying out deadlines I wasn’t sure I could meet, but this is happening, so I’ve said it. To emphasize this, if I had to pick between a date with Anna Kendrick, and making this game, I’d probably implode, as each is infinitely desirable. More on this when the time comes, but be ready to fight your greed this year.