An Introduction to HaxeFlixel with HTML5

A framework to make videogames

A talk by Ciro Durán / @chiguire
London Haxe Meetup, July 2017
Find these slides at http://www.ciroduran.com/talks/flixelmeetup2017
These slides have speaker's notes, use s to bring them up.

Hi everyone! Welcome to the London Haxe Meetup. I'm really happy to be here, talking to you. I am a game developer working in the industry, yes, but I'm not here as a professional, I am here as an amateur. Amateur is a word frequently associated with a beginner, but it's a much, much more interesting word. Merriam-Webster defines it as a person who does something for pleasure and not as a job. I think that videogames, and games in general, still have a lot of potential, but you won't see them at the GDC, much less at E3. There are dozens, hundreds of people that are amateurs, as I am, who make games because we want to scratch an emotional itch, or are very focused on a narrow target. Mine are games about my life back in Venezuela, where I was born and where I grew up. Games have lots of directions that at some point someone was taking them there, and no longer are. They also have lots of unexplored directions. Games don't have to be limited to what we see commercially, or tied to their conventions. They don't even have to be limited to a screen and a typical controller: a keyboard, a mouse or a gamepad. It is with this spirit that I will give you an introduction to HaxeFlixel today.

Today's Agenda

Install HaxeFlixel
Create a HaxeFlixel project. See its structure
Learn about states, sprites and groups
Use FlxG frontends
Collisions
Timers and Tweens
Tilemaps
Input with HaxeFlixel
Add-ons and more

Today's agenda is a walkthrough of Flixel's core features. It might seem a bit too much too fast for a one hour talk, but my aim is that you open the slides of this talk afterwards and explore the framework at your leisure. Now, you might want to make your game, and know only programming within your domain. Making games is at first hard to grasp since you might be used to applications that only respond to a user action, like a click or an http request, or applications that only run when they have all the input they need, and run for a long while before giving you an answer. Videogames are essentially different to this in the sense that they are always doing something, regardless that the player is not doing anything. Not doing something is part of the input as well. So most games differ from traditional applications by having an update loop that runs all the time, getting the input (or lack of it) from the player, affecting the game state, and showing the results on screen.

A Haxe primer...

How many of you don't know what Haxe is? (Skip this and go right if you have used Haxe before) Why Haxe? There are other languages and frameworks that are very popular in the amateur game dev scene, Unity among all of them. But my impression is that for what I do, small 2d browser based games, Unity is way too complex. Haxe allows me to cover a lot of platforms within one codebase. There is also the case, which I have not done yet, but you might, where you want to use the same language to do the client and the server. Haxe is able to compile to PHP, so web frameworks are available for games designed our it. If you want to make real-time networked games, you'll have to use something like mphx, as the http protocol won't be enough. You can also use WebSockets with haxe-ws for html5. But let's not get ahead of ourselves :-) Why HaxeFlixel/OpenFL? I come from Flash programming, this gave me a chance to port my games very easily out of the Flash player as OpenFL is a port of the Flash API. I also realised how powerful is to have type deduction, which allows you to skip type declarations until you really need them, but will also prevent you from misusing your variables. In bigger codebases, this is crucial to maintain your sanity.

Haxe is...

...the language
...and also the compiler
The Haxe language compiles for a target: cpp, html5, swf, php, lua, etc.
The Haxe Toolkit also has haxelib, a command line package manager

Some Haxe constructs


// look, ma, no type declarations
var my_little_str = "ohlala"; 
// you can't do this to a string, compiler will issue an error
my_little_str += 10;


for (i in [0...10]) { // no way to do (i = 0; i != 10; i++)


// You don't need to cast to Int when reading the array
var my_little_array = [1, 2, 3, 4];


// Macros allow cool stuff like rox-i18n. rox-i18n scans calls
// to strings like this and produces an xml for localising them
var localised_hello = "¡hola mundo!".i18n();
// produces this


  
    hello world!

Other Haxe constructs


var str_to_init = if (the_truth_is_out_there) { 
  "I want to believe";
} else { 
  "Trust no one"; 
};


enum Color { RED; GREEN; BLUE; RGB(r:Float, g:Float, b:Float); }
// works wonderfully with switch
var color_as_string = switch (color) {
  case RED: "red"; // break is not needed, no fall through
  case BLUE: "blue";
  case GREEN: "green";
  // pattern matching!
  case RGB(r,g,b): "r:"+Std.string(r)+",g:"+Std.string(g)+",b:"+Std.string(b);
}


typedef SomeData = {
  name : String,
  age : Int,
};

Developing for Haxe

For Windows: HaxeDevelop
For Macs: HaxeDevelop with wine, or atom

The best way to start, if you regularly use Windows, is to download and use HaxeDevelop. You can use HaxeDevelop in turn download and install the Haxe compiler for you. The Haxe Toolkit has the compiler and also has haxelib. It's a command line package manager. If you have a library you want to share, you share it through haxelib so anyone can easily install your package along with all your package's dependencies. You should not fear haxelib more than, say, git. Once you install HaxeDevelop and the Haxe compiler, you then call haxelib to install the latest version of HaxeFlixel. This will in turn install all its dependencies. Haxelib has a problem you won't find at first: global state. This is the reason on a past meetup Rob Konrad was insisting in version controlling his whole toolchain for Kha, another game engine. It solves the problem for him, very clever, but it solves the problem just for him. This is not a problem initially, but as HaxeFlixel has undergone heavy development and refactoring, I have had to maintain my released games so I can compile them with the latest HaxeFlixel version. It is very annoying.

Installing HaxeFlixel

In one line:


C:\> haxelib install 
       flixel            # The core framework 
       flixel-tools      # flixel command line tool 
       flixel-templates  # project templates 
       flixel-addons     # very useful, but not core stuff 
       flixel-demos      # code samples
       flixel-ui         # UI library
C:\> haxelib run lime setup
C:\> haxelib run flixel-tools setup

Creating a project from a template


C:\workspaces> flixel tpl -n "MyAwesomeProject"

Or if you don't have flixel.bat in your path:


C:\workspaces> haxelib run flixel-tools tpl -n "MyAwesomeProject"

HaxeFlixel project structure

FlxGame

A Blank FlxState

A Non-blank FlxState

FlxSprite, FlxGroup, and Assets

Initialise Sprites


var sprite = new FlxSprite(100, 10);
sprite.makeGraphic(50, 50, FlxColor.BLUE);
add(sprite);


var sprite = new FlxSprite(100, 10, "assets/mysprite.png");
add(sprite);


var sprite = new FlxSprite(100, 10, AssetPaths.mysprite__png);
add(sprite);


var sprite = new FlxSprite(100, 10);
sprite.loadRotatedGraphic("assets/box.png", rotations, frame, 
	antialiasing, autobuffer);
// rotations == 16, frame == -1, antialiasing == false, 
	autobuffer == false
add(sprite);

You can initialise blank sprites, for which you can make a graphic afterwards, either of a specific color, or transparent, so you can draw over it. You can also pass a relative path, in which case the sprite will load the image and use it fully to create the sprite. You can also use AssetPaths. You have to be careful with the image naming, as this macro ignores directories, and will fail if you have two or more images with the same name, even if they're in different parts of assets/. You can also have HaxeFlixel create the rotations of an image beforehand, trading some memory to have really fast rotating sprites. The assets/ directory is usually okay for putting all you need, you can add more asset directories in project.xml. The use of AssetPaths is left to your discretion. Autocomplete is very useful, but the file name uniqueness constraint is sometimes annoying, mostly when you are localising and need to have several files with the same name in different directories.

A Sprite strip

Sprites by Kenney.nl, free to use.

Sprite Animation


var sprite = new FlxSprite(100, 10);
sprite.loadGraphic(AssetPaths.female__png, isAnimated, 80, 110);
sprite.animation.add("idle", [13]);
sprite.animation.add("stand-right", [18]);
sprite.animation.add("stand-left", [18], 10, true, true);
sprite.animation.add("walk-right", [22, 23], 10);
sprite.animation.add("walk-left", [22, 23], 10, true, true);
add(sprite);

You may call these as part of class constructor instead for better separation of responsibilities.

Sprite Animation


class Character extends FlxSprite {
  public function new() {
    super(0, 0);
    loadGraphic(AssetPaths.female__png, true, 80, 110);
    animation.add("idle",        [13]);
    animation.add("stand-right", [18]);
    animation.add("stand-left",  [18],     10, true, true);
    animation.add("walk-right",  [22, 23], 10);
    animation.add("walk-left",   [22, 23], 10, true, true);
  }
}

Using Groups


// with some sprites created beforehand, named sprite1, sprite2...
var group = new FlxGroup();
group.add(sprite1);
group.add(sprite2);
add(group);

Texts


// import flixel.text.FlxText and flixel.util.FlxColor
var title = new FlxText(10, FlxG.height / 5 * 2, // x, y
                        FlxG.width - 20,         // width
                        "Hello world!",          // text
                        36);                     // font size
title.alignment = FlxTextAlign.CENTER;
title.color = FlxColor.MAGENTA;
add(title);

Texts are fundamental to communicate stuff, although you could make a game that uses no text at all as a design excercise. For the moment, this is a typical use. The constructor receives some basic parameters, and then you have to set some more through properties. The constructor also receives more parameters, but the defaults are usually okay. This is a good point to talk about the design of HaxeFlixel. As time has progressed, the constructor for FlxText, and some others, have become really big, with lots of parameters. It becomes difficult to remember all of them. Moreover, the amount of them makes the code not quite self-documenting as you would like. In this sense, I love the approach that libraries like Luxe/Snow take: use a typedef to contain all parameters, and pass that struct to the constructor. Haxe even allows you to have a simple way to compose structs so you don't repeat yourself on certain properties.

FlxG

FlxG.log
FlxG.watch
FlxG.html5
FlxG.random
FlxG.sound
(among others...)

As I told you before, FlxG is a huge, huge object. If you're taking away something from today, it's this style of programming, which might be... controversial. The refactoring process for HaxeFlixel has consisted in moving groups of related functionality to frontends. FlxG has several of them. For this talk we'll only check some of them. These functions and properties allow you to query the state of the game for a given update tick. It also has the function to switch a state, and the function to detect and solve collisions. Some of these frontends are: * log - Print lines to the runtime log. This is only useful in debug, as Release makes this code go away on compile time. You can emit notice, warn, or error logs. * watch - Watch is very, very useful if you need to debug something in detail. It allows you to inspect and set a value for any object. * html5 - You can check the browser, the platform it's running on, and whether it's mobile. This would allow you, for example, to show an on-screen input controller for mobile games. * random - This used to be a class full of static functions, but now it resides in FlxG, which is the correct thing to do if you want to have deterministic games. What does that mean? It means that HaxeFlixel can record the actions of a player to be able to replay them, and still come up with the same game session. This is what you can do with the VCR frontend. * sound - Sound allows you to play sound and background music. Sadly, not very sophisticated, you can only play sample files, not synthesize sounds. Since we're talking about HTML5, remember to export your audio to OGG to use it in the game. I use Audacity for this. * and others, such as... * save - for storing player state * console - you can interact with Flixel's runtime console here * debugger - the whole debug interface window * mouse, touches, swipes, keys, gamepads, etc. - All related for input (we'll see about this one at the end of the talk) * vcr - Allows to record your plays, and pause the game

Collisions


FlxG.collide(?ObjectOrGroup1 : FlxBasic, 
             ?ObjectOrGroup2 : FlxBasic, 
             ?NotifyCallback : Dynamic -> Dynamic -> Void
            ) : Bool
// examples
FlxG.collide(character, enemies); // a sprite against a group
FlxG.collide(pigeons, seagulls); // a group against a group
FlxG.collide(boxes); // members of a group against themselves

Once you have sprites, you want to be able to collide them. HaxeFlixel has a very convenient way to make them collide. FlxG.collide is your function. It works within the simple physics model of the framework, which is Axis Aligned Bounding Boxes (AABB). Your sprites have acceleration and drag, which affects your velocity, which in turn affects your position. If you wish to use HaxeFlixel's AABB collisions, you better control the sprites movements either through acceleration or velocity, but setting the position directly will make things hard for you. FlxG.collide has also a function parameter that is called after two sprites have collided and you want to be notified. You can call FlxG.collide with just a group to test collisions within that group, between two groups, between two sprites, depending on your needs. It's that flexible.

Overlap


FlxG.overlap(?ObjectOrGroup1 : FlxBasic, 
             ?ObjectOrGroup2 : FlxBasic, 
             ?NotifyCallback : Dynamic -> Dynamic -> Void, 
             ?ProcessCallback : Dynamic -> Dynamic -> Bool
            ):Bool
// FlxG.collide is FlxG.overlap with the ProcessCallback parameter 
// set to FlxObject.separate()

You can also use FlxG.overlap to have a bit more of control over how you want to process collisions. If you check out the code, FlxG.collide is just FlxG.overlap that calls an FlxObject function called separate. Check out the code and surprise yourself. AABB also means that for the purposes of your game the sprite rectangle is your collider, even if you rotate the sprite. I found about this the hard way, so I'm telling you this to make you think about the kind of games you want to make very quickly. You can change the way you do collisions with FlxG.overlap and make something a bit more sophisticated, and you can even use the Nape physics framework for a box2d-like rigid body simulation (it works!), but you need to invest some time to find out how well they work for you. You can also use pixel perfect overlap, although this has a processing cost.

FlxTimer


var timer = new FlxTimer();
timer.start(time, 
            function(t:FlxTimer) { 
                trace("I'm complete!"); 
            }, 
            loops
           );

FlxTween


FlxTween.tween(a_sprite, {alpha: 0}, time, tween_options);
// Tween options typedef
typedef TweenOptions = {
	?type:Null,
	?ease:EaseFunction,
	?onStart:TweenCallback,
	?onUpdate:TweenCallback,
	?onComplete:TweenCallback,
	?startDelay:Null,
	?loopDelay:Null
}


FlxTween.num(...); // Tween numbers, easing functions included
FlxTween.angle(...);
FlxTween.color(...);
FlxTween.linearMotion(...);
FlxTween.quadMotion(...);
FlxTween.circularMotion(...);
FlxTween.linearPath(...);

FlxTilemap


tilemap = new FlxTilemap();
tilemap.loadMapFrom2DArray( // also from Array or from CSV
  [
    [0, 1, 2, 3, 4, 5], 
    [1, 2, 3, 4, 5, 6]
  ], 
  AssetPaths.platformerPack_industrial_tilesheet__png,
  70, // frame width
  70  // frame height
);
add(tilemap);

Tilemaps were a way to save memory in limited hardware to make large levels. Now, without strict hardware limitations, tilemaps are an effort-saving measure for developers. Given a set of tiles, you can build big levels very quickly. This, of course, highly depends not just on the engine running your game, but your toolset to build such levels. Such tools are usually tied to the engine someone is making, so it's rare to see these tools out in the wild. However, there are free tools that export to a well-defined format that is independent from the engine, such as Tiled. HaxeFlixel even has loaders for these formats, so there's that. You can also rely on autotiling, which lets HaxeFlixel determine the tile it will use based on its neighbours. If you have a tile that supports it, you can use it. HaxeFlixel includes a very basic one that you can use for testing it.

Result

Input

FlxG.keyboard
FlxG.mouse
FlxG.touches
FlxG.gamepad

An example


// import flixel.input.keyboard.FlxKey;
public function inputKeys()
{
  velocity.x = 
    if (FlxG.keys.anyPressed([FlxKey.A]))      { -200; }
    else if (FlxG.keys.anyPressed([FlxKey.D])) {  200; }
    else { 0; };
}


public function detectPause()
{
  if (FlxG.keys.anyJustPressed([FlxKey.P])) { paused = !paused; }
}

Addons and more...

In your project.xml, uncomment
Interfacing with a rigid body simulator, e.g. Nape
Effect sprites

HaxeFlixel has add ons for things that are not part of the core library, but are still very useful and conveniently located. Just add flixel-addons to your project.xml. Notice that HaxeFlixel's collision system is quite simple, sometimes too simple for the thing you're doing. You are not obliged to use it, though, there is FlxNape, which is an interface to the Nape physics library. It has almost the same concepts from Eric Catto's Box2D, so you can pick it up to speed in no time if you have used it before. You hace an EffectSprite that allows you to change visual effects to sprites, but I would warn you against using these for the time being. They work very well in Flash, but in HTML5 they slow down the game to a crawl. I had to port some games I did with Flash to HTML5 and I had to turn off these effects because of that.

An Introduction to HaxeFlixel with HTML5

A framework to make videogames

Today's Agenda

A Haxe primer...

Haxe is...

Some Haxe constructs

Other Haxe constructs

Developing for Haxe

Installing HaxeFlixel

Creating a project from a template

HaxeFlixel project structure

FlxGame

A Blank FlxState

A Non-blank FlxState

FlxSprite, FlxGroup, and Assets

Initialise Sprites

A Sprite strip

Sprite Animation

Sprite Animation

Using Groups

Texts

FlxG

Collisions

Overlap

FlxTimer

FlxTween

FlxTilemap

Result

Input

An example

Addons and more...

Some final criticism...

Questions?

Thanks!