--- title: XML Format --- ## Overview Usually a simple project file is all you need to build projects using Lime or OpenFL, but it can be extended based on your needs. Here is a reference of what you can do. ### XML Schema If you are using an XSD aware XML editor you can use the following declaration to enable XML validation and type hinting/auto completion. ```xml ``` ### Conditionals First, every node in the project file format supports `if` and `unless` attributes. These are conditional values to help you customize your build process, based upon a number of values. Here are some of the default values: - mobile, desktop or web - ios, android, windows, mac, linux or html5 - cpp, neko, flash or js You can [``](#set) or [``](#define) values for conditional logic: ```xml ``` Both also support a `value` attribute, which can be retrieved later using the `${}` syntax. ```xml ``` You can also check values that were defined on the command line: ```sh lime test flash -Dblue ``` ```xml ``` If you need to have multiple values in a conditional, spaces imply an "and" and vertical bars imply an "or", like this: ```xml ``` If a value isn't found, either because it was never set or because of [``](#unset)/[``](#undefine), it will be treated as `false`. ### Build info The `${}` syntax can get information about the build. You can use this data in a condition, print it, or pass it along to Haxe: ```xml ``` ### Duplicates You can include more than one copy of each tag, so do not worry about putting it all in one place. All of the values you define will be used. If you define the same value more than once, the last definition will be used. ```xml ``` ### include.xml If you create a haxelib, you can add _include.xml_ to the top-level directory. The build tools will automatically add the contents of the file to the user's project. You can use this to add binary dependencies, additional classpaths, etc. ## XML Tag Glossary ### app The `` tag sets values important to building your project, including the entry point (main class), the output file directory, or if you want to customize the executable filename or define a custom preloader for a web platform: ```xml ``` You can retrieve this information later: ```xml ``` ### architecture Use `` tags to set or exclude target-specific architectures. Depending on the target, values can include `arm64`, `armv7`, `armv7s`, `armv6`, `armv5`, `x86`, and `x64`. By default, the only architecture built for Android will be `armv7`. For example, if you want to enable `armv6` and disable `armv7` you would set the `` tag to: ```xml ``` ### assets Use asset nodes to add resources to your project, available using `lime.Assets`. The path attribute can point to either a file or a directory. These files will be copied (or embedded) in your final project, and can be accessed using the `lime.Assets` class. For example, if you include the following node in your project file: ```xml ``` You can access it in your application like this: ```haxe var bitmapData = Assets.getBitmapData ("images/MyImage.png"); ``` The target path will mirror the source path by default, but you also can include a rename attribute, if you wish to use a different target path. The `lime.Assets` class will use the _target_ path by default, so using the rename attribute will alter the names you use to reference your files. If you would prefer to set the ID for your asset file yourself, use an "id" attribute. This only applies to asset nodes which point to a file, not a directory path. When pointing to a directory, you can use the include or exclude attributes to specify patterns for including files automatically. Wildcards are supported. To include all the files under the directory, for example, use an include value of "*". You can separate multiple patterns using "\|" characters. You can nest assets nodes inside of each other. If you specify a directory in the top assets node, its path will be appended to the paths you specify in subsequent nodes. The type for each file will be determined automatically, based on each file extension, but you can use the type attribute to set it for the file or directory yourself. If you are nesting a node inside of another assets node, you can also use the name of the type as the name of your node. These are the current types: - binary - font - image - music - sound - template - text Some targets can only support playing one music file at a time. You should use "music" for files which are designed to play as background music, and "sound" for all other audio. "binary" and "text" are generic types which are available as a ByteArray or String in your application. Most targets can use them interchangeably. If an asset is specified as "template", it will not be copied/embedded as an ordinary asset, but instead will be copied to the root directory of your project, so you can replace any of the template HX, HXML or platform-specific files for the target. ```xml ``` ### certificate Use `` tags to add a keystore for release signing on certain platforms. If you do not include the password attribute, you will be prompted for your certificate password at the command-line. For Android, the alias will be set to the file name of your certificate by default, without the extension. If the alias name is different, you can use the alias attribute. If you have set the password attribute, the alias_password attribute will default to the same value. Otherwise you can add an alias-password attribute to specify a different value. ```xml ``` iOS does not use a certificate `path` and `password`, but instead uses a `team-id` attribute matching the ID provided in the Apple Developer portal for your team: ```xml ``` You can retrieve this information later: ```xml ``` ### classpath Same as [``](#source). ### compilerflag Same as [``](#haxeflag). ### config Use `` tags to set platform-specific values. See [config options](config) for the full list. ```xml ``` You can retrieve this information later: ```xml ``` ### define Use `` tags to set variables for conditional logic. See the [Conditionals](#conditionals) section above, and see [``](#undefine) to remove a defined value. ```xml ``` These values will be available in Haxe and in [templates](#template). For templates, use the syntax `::DEFINE_CUSTOM_VALUE::`. Hyphens are converted to underscores in both cases. ### dependency Use `` tags to specify native frameworks or references that are required to compile your project, as well as additional libraries you need copied. When targeting [iOS](../../advanced-setup/ios/), it may be used to add a native framework. ```xml ``` When targeting [Android](../../advanced-setup/android/), it may be used to add a native library. ```xml ``` When targeting [Adobe AIR](../../advanced-setup/air/), it may be used to add a native extension. ```xml ``` ### echo Prints a specified message to the console. ```xml ``` The `` element is often combined with `if` or `unless`. ```xml ``` Or it may be added inside a `
` element: ```xml
``` ### error Logs an error with `lime.utils.Log.error()` which by default throws `value` message and stops compilation (if `lime.utils.Log.throwErrors` is set to `true`). The `` element is often combined with `if` or `unless`. ```xml
``` ### haxedef Use `` tags to add Haxe defines (similar to using a [``](#haxeflag) with "-D"): ```xml ``` ### haxeflag Use `` tags to add additional [Haxe compiler arguments](https://haxe.org/manual/compiler-usage.html): ```xml ``` ### haxelib Use `` tags to include [Haxe libraries](https://lib.haxe.org): ```xml ``` You can specify a version or path, if you prefer: ```xml ``` By default, an error will be thrown if the requested library isn't installed. You can set `optional` to continue without the library instead. ```xml ``` If you have multiple Haxelib repository folders, you can select one using the `repository` attribute. The folder you select must include a copy of Lime (and OpenFL, if applicable). ```xml ``` ### icon Use `` nodes to add icon files to your project. When the command-line tools request icons for a target platform, it will either use an exact size match you have provided, or it will attempt to find the closest match possible and resize. If you include an SVG vector icon, it should prefer this file over resizing bitmap files. ```xml ``` ### include Use `` tags to add the tags found in another project file, or to find an _include.xml_ file in the target directory: ```xml ``` ### java Use `` tags to add Java classes to the project when targeting Android: ```xml ``` ### language Adds a language to the list of supported languages (by default the list is empty). ```xml ``` ### launchImage Sets the path to launch image of the app (image which will be shown at application start up) ```xml ``` ### launchStoryboard Sets the launch screen storyboard (useful only for iOS development). ```xml ``` or ```xml ``` You can also use `template` for this purpose. #### The default template The launch storyboard feature uses Haxe templates and your _project.xml_ configuration to generate an Xcode storyboard file. Lime includes one default storyboard template `splash.storyboard`, which can be configured with the following options. ```xml ``` `template` is the specific storyboard template you’re using, chosen from the templates available at `templates/ios/storyboards`. `assetsPath` is the path from your openfl/lime project root to where your launch storyboard images are saved. `bg` is a hexadecimal formatted color to use as the background, in case you’re not using a full-screen content mode. `contentMode` determines how the image scales to fit the screen. - `center` is unscaled - `scaleAspectFill` scales to fill the entire screen, with original aspect ratio - `scaleAspectFit` scales to fit inside the screen (letterbox), with original aspect ratio - `scaleToFill` stretches the image to fill the screen There are three optional attributes, (`portrait`, `landscape` and `ipad`) which you can choose from based on the target devices and orientation of your game. (The above example includes just ipad and portrait.) - `ipad` determines the image to use for iPads. - `portrait` determines the image to use for iPods and iPhones in portrait orientation. - `landscape` determines the image to use for iPods and iPhones in landscape orientation. Finally, you have the `imageset` child elements. For each imageset, lime looks for `{name}.png`, `{name}@2x.png`, and `{name}@3x.png` in the specified `assetsPath`, copying any of those that exist into an Xcode imageset. Most iPhones these days require the @2x or @3x image, while iPads require @2x. #### About templates and custom storyboard `template`, `assetsPath`, and the `imageset` elements are standard parts of the configuration. All the other attributes listed above are available based on the chosen default template, `splash.storyboard`. If the default template doesn’t meet your needs, you have two options, but both require you to open your exported iOS project in Xcode and create your own storyboard. 1. Take the storyboard you built in Xcode and put it into your project. In this case, you would use the name or path attribute instead of template, and you would have no template-specific attributes to set, but you would still need to provide the appropriate imagesets. ```xml ``` 2. Using the default template as an example, take the storyboard you built in Xcode and add it to your lime templates. You would use it in the same manner as the default template, but use any attributes you specified instead. ### library All assets go into the "default" library, but by adding `` tags it is possible to modify the default library and also define additional libraries and load/unload them as needed. To disable preloading on the default library: ```xml ``` To load assets at runtime: ```haxe Assets.loadLibrary ("default").onComplete (function (library) { var bitmapData = Assets.getBitmapData ("default:image.png"); // or var bitmapData = Assets.getBitmapData ("image.png"); // "default:" prefix is implied, if no library prefix is included }); ``` #### Using Additional Asset Libraries You can easily add assets to libraries other than the "default" library. These are not preloaded by default, unless you add: ```xml ``` Then to have certain assets allocated to the above library: ```xml ``` Be sure to specify the correct library when retrieving the assets in your code. See the above example for using the library prefix. You can also use `Assets.unloadLibrary` when you are doing using those resources. ### log Logs an error (see [``](#error)), warning or info message. Examples: ```xml ``` The `` element is often combined with `if` or `unless`. ```xml ``` ```xml ``` Or it may be added inside a `
` element: ```xml
``` ### meta Use `` tags to add information about your application, which usually will not affect how the application runs, but how it is identified to the target operating system or on an application store: ```xml ``` You can retrieve this information later: ```xml ``` ### module More to come. ### ndll You can use `` tags to include native libraries. These are usually located under an "ndll" directory, with additional directories based upon the target platform. Usually an `` tag will be included as a part of an extension, and is rare to be used directly: ```xml ``` ### output **Deprecated!** Use the [``](#app) element instead. Can be used for setting app file name, app path and app swf-version: ```xml ``` ### path Use `` tags to add directories to your system's PATH environment variable. ```xml ``` ### postbuild Lets you set post-build commands such as Haxe code (interpeted by the Haxe interpreter), a run file command, or a console command. ```xml ``` ### prebuild Lets you set pre-build commands such as Haxe code (interpeted by the Haxe interpreter), a run file command, or a console command: ```xml ``` ### preloader **Deprecated!** Use [``](#app) instead. ```xml ``` ### sample In a library that targets Lime, makes a sample available using the `lime create` command. ```xml ``` Then you can use: ```sh lime create flixel:Arcade ``` ### section The `
` tag is used to group other tags together. This is usually most valuable when combined with "if" and/or "unless" logic: ```xml
``` ### set Use `` tags to set variables for conditional logic. See the [Conditionals](#conditionals) section above, and see [``](#unset) to remove a set value. ```xml ``` These values will be available in [templates](#template) using the syntax `::SET_CUSTOM_VALUE::`. (Hyphens are converted to underscores.) ### setenv Use `` tags to set environment variables. See the [Conditionals](#conditionals) section above. ```xml ``` ### source Use `` tags to add Haxe class paths: ```xml ``` If you are using `@:file`, `@:bitmap`, `@:sound` or `@:file` tags in your project, be sure that the asset files are available within your Haxe source paths. ### splashscreen Same as [``](#launchimage). ### ssl Not implemented ### swf See [``](#library). ### target Lets you redefine the build process for a specific target by running a custom haxelib command. This might be useful if you want to use your own library for building your project, i.e. you know what you're doing and you know how the Lime build system works. ```xml ``` ### template Use `