NMML File Format

Introduction

NME includes an "install tool" which automates the compile and packaging process for each supported target. This makes it very simple to publish an existing project for a new platform, or all the supported platforms.

Each tutorial, sample or project template should have an NMML file already that you can use to build the project. However, as you begin to customize your own project, you may wish to delve deeper into the features and options that are available in the project file format.

File Basics 

Each NMML project is written in an XML format. You can modify an existing project file or create your own using your choice of text editors.

Here is an example of a generic project file:

<?xml version="1.0" encoding="utf-8"?>
<project>
 
	<app title="My Project" main="MyProject" 
		package="org.example.myproject" version="1.0.0" 
		company="NME" ></app>
 
	<window width="320" height="480" fps="30" orientation="portrait" 
		resizable="true" ></window>
 
	<set name="BUILD_DIR" value="Export" ></set>
 
	<classpath name="Source" ></classpath>
	<haxelib name="nme" ></haxelib>
 
	<icon path="Assets/nme.svg" ></icon>
 
	<assets path="Assets" rename="assets" include="*" exclude="nme.svg" ></assets>
 
	<ndll name="std" ></ndll>
	<ndll name="regexp" ></ndll>
	<ndll name="zlib" ></ndll>
	<ndll name="nme" haxelib="nme" ></ndll>
 
</project>

The <app> Node

The app node controls general settings about your application, like the code entry point or the meta data to use while packaging.

title – The name of your application
file – The name that will be used when creating your executable (Default: "MyApplication")
package – The package identifier used when publishing your application (Default: "com.example.myapp")
version – The version number for your application (Default: "1.0.0")
company – The publisher name for your application (Default: "Example Inc.")

The <window> Node

The window node controls how your application will be displayed on each platform. Though most properties are supported by all targets, some will be ignored. For example, "hardware" is ignored when publishing to Flash.

width – The width of your application in pixels. Use zero to display fullscreen (Default: "640")
height – The height of your application in pixels. Use zero to display fullscreen (Default: "480")
orientation – Set the application's orientation. Values include "portrait" and "landscape" (Default: "")
fps – Control the framerate of your application. A value of 30 is common (Default: 60)
background – Set the background color of your application (Default: "0xFFFFFF")
hardware – Toggle between hardware and software rendering (Default: "true")
resizable – Control whether the application window is resizable (Default: "true")

<set>, <unset>, "if" and "unless"

You can use the set and unset node tags to shape the values that are defined for the install tool. There are some values that are preset in the install tool which you can customize, or you can create your own.

Every node supports an "if" and an "unless" attribute, which can be used for conditional compiling. For example, when you compile for Windows, "target_windows" is automatically defined as true. If you add "if='target_windows'" to an , or other kind of node, it will only be executed if "target_windows" is true. Likewise, the "unless" attribute can be used to ignore tags when a property is true.

Some of the settings you can configure for the install tool are "BUILD_DIR", which sets the output directory when building your project, or "SWF_VERSION", which manages the SWF version when compiling for Flash. The default Flash version is "10"

The <classpath> Node

You can use the classpath node to include a Haxe source code directory when compiling your project. Set the "name" attribute to the relative or absolute path to your target directory.

The <haxelib> Node

In addition to classpaths, you can use the haxelib node to include code from an installed library off of haxelib. You will want to include a node that pulls code from NME, but you can also add more, depending on the libraries you decide to use. Set the "name" attribute to the name of the library you have installed.

The <icon> Node

NME can generate icons for you, based on the platform you target. Depending on the target you choose, NME will look for icons of specific sizes.

You can set the "path" attribute to a relative or absolute path for the file you are using as an icon. If this file is an SVG vector graphic, it can be used for any size icon NME needs during the compile process.

If you are using bitmap icons, specify "width" and "height" attributes that match the file you are adding. Add multiple icon nodes with different width and height values to match the required sizes for each platform you target.

The <assets> Node

The assets node is the most robust node type in an NMML project file. You can use asset nodes to customize the files you would like to include in your project, and how they should be treated.

File types are determined automatically based on the extensions of your files. Valid types include "sound", "music", "font" and "image". Either you can allow the install tool to assign types automatically, or you can use the "type" attribute to set the type for your files, or you can actually add child nodes beneath your  node, using the type you wish to use as the name of the node.

path – A relative or absolute directory or file path to include
rename – Use this attribute if the output path should differ from the input path
type – Manually set the file or files to a specific file type
include – Define a filter that specifies file or directory name patterns that should be included
exclude – Define a filter that specifies file or directory name patterns that should be excluded

The <ndll> Node

You can include precompiled native libraries with your project. By default, you will want to include NME and some other standard libraries. If you create or use a native extension to NME, you can use these tags to make sure that your native libraries are included.

The "name" attribute controls the name of the library. The install tool will look in your project directory or the HXCPP project to find files. If you specify a "haxelib" attribute, the install tool will also look under "/ndll/(target name)/" for the requested library.

The <extension> Node

If you are adding an extension to NME, the easiest way to include it in your project is probably to use an extension node. This makes it possible to include extensions that are not located in your project directory, or in haxelib.

You can specify a "name" attribute for the extension name the install tool should expect, as well as a "path" attribute for the relative or absolute file path where the extension is located.

The path that you specify will be added as a classpath, and compiled libraries will be expected under "/ndll/(target name)" for each platform you compile against.

<section> and <include> 

You can group your nodes underneath section nodes, which may be especially useful in combination with the "if" or "unless" attributes for conditional compilation. You can also specify include nodes to parse an external XML file. Include nodes expect a "path" attribute for the relative or absolute path to the file you wish to also have parsed.

<haxedef>, <compilerflag>, <setenv> and <path> 

It can be somewhat confusing how these node types relate to each other, so it helps to understand the compile process.

The NME install tool prepares for a build, then prompts the Haxe compiler to build your project. If you are targeting a C++ target, part of this process will be running the native compiler toolchain for your target platform.

The haxedef node will add a define ("-D ") to the command line when running the Haxe compiler. The compilerflag node will pass an additional option to the Haxe compiler. This could be a define, like "-Dwebos", or something completely different. This is one way to customize the compile process. Both of these tags expect a "name" attribute, with the define or compile parameter you wish to pass to Haxe.

Throughout the entire build process, the command line or terminal will be used to run Haxe, your compiler toolchain, and for some targets, to package your application. You can use setenv to set an environment variable for the command line, or path to add a value to your PATH. Don't worry if you don't understand PATH or environment variables -- these tags are generally only needed for advanced compilation. These nodes also expect a "name" attribute.

The <certificate> Node

If you would like to create a release APK for Android, you will need to sign it using a certificate. For more information on creating a certificate that you can use with your application, visit this page.

Set the "path" attribute to the location of your certificate. By default, the alias name will be set to the name of your certificate (minus the path and extension). Otherwise, you can specify the alias name using an "alias" attribute.

If you do not provide a password, you will be prompted to provide a password while building your application. Otherwise, you can add a "password" attribute to have this completed automatically. If your alias password is different than the certificate password, you can specify an "alias_password" attribute, otherwise "password" will be used for both.