FlxRes

If you are using GameMaker Studio 2, check out the Advanced Resolution Manager. It is free and open source!

In my coding and game development journey, I have tried and even used in production several engines or frameworks, like Adobe AIR with pure flash (vector and CPU accelerated), Adobe AIR with Starling, GameMaker Studio 2, and HaxeFlixel to name some of them. One of the early challenges I had to face was common in all of them. Make my project/game looks as it should, in any screen, any resolution. Nowadays, on most platforms and especially the mobile platform, there are countless different screens of various sizes and aspect ratios. FlxRes hopefully will handle the logic/code part of the job, letting you focus on other aspects of your project.

FlxRes is a simple but effective resolution handler for HaxeFlixel, absolutely free (MIT License), open source and very easy to use.

Contents

• Overview and API
• Prerequisites, Compatibility and Limitations
• Download links
• The problem FlxRes solves
• How to use FlxRes
• Design width vs design height
• Using high definition assets
• Support this project
• Credits

Overview

FlxRes hopefully can make your project looks as it should on any screen, any resolution. FlxRes is easy multiresolution handling for HaxeFlixel. Its primary goal is to be simple, easy to use and accessible to beginners.

API overview

// provide the width, get the height
height = FlxRes.getOtherDimension(width, false);

// if you ommit the second argument, it will be assumed as false
height = FlxRes.getOtherDimension(width);

// provide the height, get the width
width = FlxRes.getOtherDimension(height, true);

// get the aspect ratio of screen (if full screen) or the game window (if windowed)
ratio = FlxRes.getRatio();

// get the diagonal of screen (if full screen) or the game window (if windowed) in inches 
diagonal = FlxRes.getDiagonal();

// returns true is the orientation is landscape
if (Flx.isLandscale()) trace("the orientation is landscape");

//  returns true is the orientation is portrait
if (Flx.isPortrait()) trace("the orientation is portrait");

Prerequisites, Compatibility and Limitations

Prerequisites

This project requires to have installed the HaxeFlixel. Additionally you should have some basic familiarity with HaxeFlixel. At very minimum, you should be able to create a new project, edit it in your IDE of choice and build it for your desired target platform.

New to HaxeFlixel? Get started here!

Compatibility

This project should be compatible with all target platforms HaxeFlixel can export to. Please note that HTML5 has some issues (see the HTML5 builds at the bottom of this page).

Limitations

This project is not suitable if you want your project to has dynamic orientation on mobile targets. Provided that I can figure out an easy and beginner friendly way to implement it, I will add this feature in a future update. Additionally this project is for HaxeFlixel, thus, any limitations that may apply to HaxeFlixels, will apply to this project too.

Download links

• This repository contains the FlxRes within an example project. You can fork/clone/download this project and follow this readme which is actually a tutorial on how to use FlxRes.
• You can also find this example project packed as zip on itch.io
• The assets and the extra code for the example can be removed easily. However you can download an empty template project containing only FlxRes on itch.io or as release from this repo.

The problem FlxRes solves

If you are familiar with the black bars problem, skip this section

Let's see the problem FlxRes is trying to solve! Let's say you want to make a pixel art game. You have decided that your design resolution is 320x240.

The design resolution, is the resolution that your graphic assets look as they should, without using any scaling. When designing your game you should make some design decisions early, to avoid redoing work later. Design resolution is one of the most important decision you should decide as early as possible.

Create a new HaxeFlixel project, and go to the Main.hx file in source folder. Change the following line in public function new()

addChild (new FlxGame(0, 0, PlayState));

to

addChild (new FlxGame(320, 240, PlayState));

You just set your design resolution to HaxeFlixel! Let's add a background color. Go to PlayState.hx in source folder and add this line in override public function create() under super.create();

bgColor = FlxColor.BLUE;

Let's try it on full screen. Go to Project.xml at the root folder of your project and change the line 25 the fullscreen from false to true.

Now build the project with neko or hashlink. The chances that your monitor aspect ratio is not 1.33 are high, so you possibly will see something like this:

The black bars are not part of your game, but are part of the game's screen and the gaming experience. If we remove the values of the resolution we previously hard coded in Main.hx the black bars will be removedbut then we are not providing the desired resolution. A pixel art game with 320x240 design resolution assets would look tiny in a FHD screen.

The black bars problems can be solved by the FlxRes. Additionally, FlxRes will automatically remove the black bars that might appear even in windowed mode, without any hard coding on your part.

How to use FlxRes

Clone or download this repository which contains the example project and open it with your favorite IDE. Then built it with neko or hashlink. You will see a window with dimensions 640x480px (the default window size of a new empty HaxeFlixel project). You will also see a skeleton patrolling inside a cave. The skeleton's logic is patrolling from the edge of one side to the other, ensuring us that the resulted width of FlexRes calculations is correct. If the patrolling was shorter than the width of the window or longer (leaving outside of window) we could instantly tell.

The results of the FlexRes are not obvious now because the size of the window (640x480px) are double than our design resolution (320x240px), thus the result would be the same without FlexRes.

Now go to Project.xml and change at line 25 the fullscreen from false to true.

Build again the project with neko of hashlink. You will see the following:

As we saw in the previous section "The Problem FlxRes solves", normally we would see black bars left and right on the screen, but thanks to FlexRes this problem is solved! Switch back in Project.xml at line 25, the fullscreen from true to false. Next, we will inspect the source code and the assets of this example project.

The FlexRes class

Lets see the FlexRes class first. Go to source\flxres folder and open the FlexRes.hx file. We see a single static public function. That means that we can call this function whenever we want and from everywhere without creating an instance of FlexRes class.

This is how to use the function:

otherDimension = FlxRes.getOtherDimension(designValue, returnWidth);

The first argument designValue we pass the design or ideal width or height as integer. The assumption of design value as width or height is based on returnWidth.

The second argument is optional and is a Boolean. If omitted will be assumed as false. If we pass true, it will return the other dimension as width and will assume the designValue as height. If we pass false, it will return the other dimension as height and will assume the designValue as width. It will return the other dimension to otherDimension variable, based on the 2 arguments we pass. When we finally have both the ideal width and height, we will be able to create a new FlxGame with the ideal resolution.

If you are experienced enough as programmer, you will not only notice the small size of this class, but also its simplicity. While this is simple for an experienced programmer, it is the code I wish I could find when I got started. This code is for and dedicated to every beginner that just started coding with HaxeFlixel.

The assets of the example

Now let's see the assets of the example:

• The design resolution is 320x240px
• The bg1.png and bg2.png images are 416x208px
• The skeleton sprite is 45x51px
• And the ground tile is 32x33px

The assets can be found in the assets\images folder.

Using FlexRes with design width on landscape orientation

Let's inspect the Main.hx a bit. Under class Main extends Sprite there are 2 constants the DESIGN_WIDTH and the DESIGN_HEIGHT. Their values match the design resolution.

Let's see inside the public function new(). We declare two local variables _width and _height. We also declare the returnWidth variable as false. That means that we will provide to FlxRes the width as design value and it will calculate the other dimension, thus, the height (lines 39-40). Notice that we omitted the 2nd argument. It is optional and omitting it, means false.

Now go to Project.xml and at line 19 change the width from 640 to 900. Also make sure that you have switched back the fullscreen from true to