HXP Projects && Template Directories

If you look closely at the OpenFL “docs” page, you’ll notice it lists two options under “project files.” The first of the two is the XML format you know and love, or at least know, but what’s up with the second?

Before I answer that question, I have some questions for you to answer.

Is your project file getting out of hand? Do you wish the XML format supported string manipulation? Do you find yourself typing out multiple <set> tags to simulate the “or” operator? Have you ever tried and failed to copy a directory with the <template> tag?

If you answered “yes” to any of these questions, HXP files may be right for you. Consult your physician today!

So anyway, what are HXP files? The short answer is, they’re HX files with an extra P.

The P stands for “Project,” so the long answer is, they’re project files which let you use Haxe instead of XML. You can write functions, manipulate strings, declare variables, and even access Haxe’s standard library.

Let’s try it out!

Ok, find a sample project that uses an HXP file, and… oh. There aren’t any, are there?

Fine, we’ll use DisplayingABitmap. I’ve created an HXP version of the project file, available here. Save it as project.hxp, delete project.xml, and you’re ready to give it a try.

Lime recognizes the file format, so just run lime test flash and it’ll find the new project file. It should show the OpenFL logo in the middle of the screen.

Congratulations! Through no fault of your own, you have gotten an HXP project file to work!

Converting your XML file to HXP

Running a sample project is all well and good, but what about that much larger project file you want to convert? Or perhaps that large file that you don’t want to convert because it will be so much work, but you have to convert anyway? Either way works.

To start, let’s reduce the amount of typing you need to do. Haxe has a wonderful feature known as “functions” (you may have heard of them), and I’ve written a set of functions that match some of the tags used in XML project files. Paste them at the end of project.hxp so that you don’t have to scroll past them each time.

Here’s a conversion guide:

<set name="godMode" />
    defines.set("godMode", 1);
    //Or if you only need it for conditionals:
    var godMode:Bool = true;

<setenv name="DARK_AND_STORMY_NIGHT" />
    setenv("DARK_AND_STORMY_NIGHT", "1");
    //That second value must be a string and cannot be skipped.

<setenv name="TRUE" value="FALSE" />
    setenv("TRUE", "FALSE");
    //Please do not do this.

<haxedef name="sburb" />
    haxedefs["sburb"] = 1;
    //Please do not do this either.

<haxedef name="dump=pretty" />
    haxedefs["dump"] = "pretty";

<haxeflag name="-dce" value="std" />
    haxeflags.push("-dce std");

<section if="flash"> </section>
    if(target == Platform.FLASH) { }

<section if="godMode" unless="mobile"> </section>
    if(defines.exists("godMode") && platformType != PlatformType.MOBILE) { }

<ndll name="regexp" />

<assets path="assets/text" rename="text" include="*.txt|*xml" exclude="*.rtf" />
    includeAssets("assets/text", "text", ["*.txt", "*.xml"], ["*.rtf"]);

<certificate path="correcthorse.keystore" password="batterystaple" alias="AzureDiamond" alias-password="hunter2" />
    certificate = new Keystore("correcthorse.keystore", "batterystaple", "AzureDiamond", "hunter2");

<dependency name="GooglePlayServices" path="pathtoGooglePlayServices" />
    dependency("GooglePlayServices", "path\to\GooglePlayServices");

<dependency name="GameKit.framework" />

<dependency path="/Library/Frameworks/LameKit.framework" />
    //This is where Apple recommends you place your custom frameworks.

<include path="industrial/application.xml" />
    merge(new ProjectXMLParser("industrial/application.xml", defines));

<template path="templates/CureForCancer.java" rename="src/com/jir/research/CureForCancer.java" />
    templateFile("templates/CureForCancer.java", "src/com/jir/research/CureForCancer.java");

<template path="templates/" />
    //Currently this is not working correctly, and even if it was,
    //it wouldn't do exactly what you'd expect. So...

<template path="spam/eggs/" rename="res/camelot/" />
    templateDirectory("spam/eggs/", "res/camelot/");
    //Note: The XML version is purely hypothetical. You have to
    //use HXP to copy a directory directly.

If that isn’t enough, or if I got something wrong, refer to the source. (Also be sure to let me know.)

One step at a time

If this is too much work to do all at once, then keep your old project file around, and import it into the new one:

merge(new ProjectXMLParser("old_application.xml", defines));

With that done, you’re free to move items over one at a time. Just be warned that some features, such as the <template> tag for folders, may quit working correctly. If this happens, focus on converting them first.

Leave a Reply

Your email address will not be published. Required fields are marked *