When I first started using HaxeFlixel, the biggest turn off was definitely the giant stack of programs I needed to install. Worse yet, I had no idea what half of them even did so I just had to blindly install them all and hope that nothing broke along the way.
Now that I’ve had a bit more time to use HaxeFlixel I realize the install process isn’t as daunting as it first seems. In fact, it’s pretty straightforward once you understand what everything does.
The following guide is a lot longer than what you’ll find on the HaxeFlixel website, but the idea is to explain the individual components that make up the install process. This is so when something breaks you’ll hopefully understand how to fix it. When I first started using HaxeFlixel the website I was downloading the libraries from went wonky, fell over, got a bucket stuck on its head and then one of the components went completely bonkers. I didn’t know what the hell the component even did so I just deleted everything and started again.
Note: This guide assumes you are installing on Windows.
Visit http://haxe.org and download the Windows installer. Once it’s installed, go to “Start > Control Panel > Search for Environment Variables > Edit system variables” and then click the Environment Variables button. In the screen that appears you have two types of variables, local at the top and system at the bottom. In the system variables check that you have a variable called “HAXEPATH” set to the same directory you installed Haxe.
Note: If you are installing Haxe through Chocolatey sometimes the environment variable will be installed under “HAXE_PATH”. It should be changed to “HAXEPATH’. You might need to restart your computer after changing this variable. I’ve also noticed that sometimes it wont setup this variables at all, in which case you’ll have to manually add it in. Also make sure you have “NEKO_INSTPATH”.
When I first started with HaxeFlixel the tutorials made it seem like I had to install OpenFL manually. This is probably where everything starts to go sideways for most new users and it’s not the best idea to be installing all the packages by hand. Instead, Haxe comes with a a very handy tool called HaxeLib. HaxeLib is a package manager similar to Nuget, npm, Bower or other tools. Now that we have Haxe installed we don’t actually need to install anything else manually, we can just cram stuff into the command line and let it install what it needs. Huzah!
To start, open your command line by going “Start > Run” type “cmd” and hit enter. This should open your command console. Next, enter these commands one at a time:
haxelib install lime haxelib run lime setup
Timeout Errors: If you start getting timeout errors when using Haxelib, just wait 10-15 minutes and try again. Sometimes it gets hit by heavy traffic and sometimes (rarely) it goes down completely. If you are getting the timeout errors for an extended period of time you can download and install the packages locally by visiting lib.haxe.org directly. Once you’ve downloaded the correct package, in your command line make sure the path you are at contains the zip file and then replace the keyword ‘install’ above with the keyword ‘local’ – this will make haxelib install from your local .zip file instead. Also just make sure that you replace ‘lime’ with the full zip file name of the download (which will look something like “lime-2,5,0.zip”).
Lime is the most basic layer of our rendering engine. It’s a very low level system that supports many platforms, such as Flash, HTML5, as well as native platforms like Windows and Android. It’s part of the glue between Haxe and the devices you compile too, plus it has one of the best icons around. Look at it! It’s a lime and a cube!
Lime alone can be quite difficult to write too, which is where OpenFL enters the scene – it’s a layer that sits on top of Lime and gives it a much nicer API to program against.
OpenFL is a framework that is built to run on top of Lime. It’s a rewrite of the Actionscript3 library with some extra additions thrown in for device support. It’s very cool and gives us the ability to write in framework that is a lot closer to Actionscript. Without OpenFL we would have to write in OpenGL directly, which isn’t fun for most indie devs. We do lose out on some of the advanced functionality you get with Lime by having direct access to OpenGL, but from what I’ve seen that’s rarely an issue.
So why does this matter for us? Well OpenFL is what allows the “Flixel” part of “HaxeFlixel”. Flixel is a flash game engine written by Adam North, but since Flash isn’t that flash these days (HA!) some smart people re-wrote it in Haxe on top of the OpenFL engine (and OpenFL lets us export to more platforms than just Flash). That’s why some people refer to OpenFL Actionscript 4 and HaxeFlixel as Flixel 2.
Now that we’ve already installed Lime, we can install OpenFL to give us a nice API on top. In your command line run the following one at a time:
lime install openfl
This will install OpenFL on your computer. Note that in this case we didn’t install this through haxelib because Lime will take care of setting up OpenFL for us.
One that is done we need to choose what platforms we want Lime to build to. You’ll notice that we don’t need to setup HTML5 support, it’s setup by default.
lime setup windows
If you also want to build to Android, you can run the following:
lime setup android
Warning: If you do not plan on building to Android and you have never installed the SDK before, do not run this command. It will download an absolute craptacular amount of files and require you to do some manual steps in between to setup Java developer kits. I would actually recommend setting up all this in advance manually by following this guide on the Android site and then coming back and finishing this install.
Between all these libraries and frameworks we actually still need to install HaxeFlixel! We have our base setup now, which looks like:
So our last step is to run the following.
haxelib install flixel haxelib install flixel-tools haxelib run flixel-tools setup
This will install Flixel from the haxelib library, plus it will download a set of tools that make development much easier.
When you setup flixel-tools you will be asked if you want to setup a flixel alias in your console. It is highly advised you set this up. This allows you to write shortcut commands like ‘flixel tpl’ to setup a boilerplate project ready to go.
You will also be asked what IDE you are using. Don’t do what I did which is press a random number and hope to fix it later. Whatever option you select will determine what format your projects get created in (using the command alias above), so if you choose Flash Develop you will get .hxproj files, but if you choose IntelliJ you will get .idea files. If you don’t know which one to choose, just select Flash Develop.
Note: It is possible that after you’ve installed Haxe you can just skip to the command above. Lime and OpenFL are marked as dependencies that haxelib will automatically download when you install flixel. However, I recommend setting them up separately just so that you can do any extra steps you need like setting up Lime for windows/android.
Confusingly, Flixel is actually HaxeFlixel, it just doesn’t seem like it. Because haxelib is a collection of libraries written in Haxe, the version they contain is the actually the Haxe version of Flixel. This can be strange for new users because your downloading a framework called Flixel, but everyone keeps calling it HaxeFlixel.
HaxeFlixel is more of a collection of tools and frameworks under the umbrella project of HaxeFlixel, all supported by a core group of open source developers, rather than a single program like Unity or Stencil. So when you get HaxeFlixel, you’re actually pulling in several different tools and libraries (OpenFL, Lime, Flixel etc.) which all combine together to make a game engine. It’s both what makes the project so cool, but also very confusing to get started.
Visit www.flashdevelop.org and download the latest version.
Once you’ve installed it, open it up and go to: “Tools > Install Software” and tick “Standalone debug flash player”. This will download the Flash debugger we need for our project. At this point we can create a new blank project either by using the command line, or we can download a template that allows us to create a new flixel project from inside Flash Develop.
I also recommend downloading and installing the templates from this page: http://haxeflixel.com/download. If you are still using Flash Develop, download ‘FlashDevelop .fdz template’ and then run the file it gives you. You will probably have to restart Flash Develop. There is also a package just called “Flash Develop Template” which is just a raw dump of the boilerplate project – this can be handy if you want to customize the project template and use that as your starting point (I have a slightly modified version I use for game jams).
Everything should be setup ready to go now. There’s some tricks you can now do like ‘haxelib upgrade’ to update all the libraries and plugins you’ve downloaded. and there’s some great plugins out there that you can also download (don’t forget that as long as it doesn’t need to render anything, pretty much any Haxe plugin can be used in your game). I may do a follow up post on getting started with Flash Develop (including the extremely finicky debugger) and cover some good boiler templates that are out there to get started.