diff --git a/standalone-openfl-app/.gitignore b/standalone-openfl-app/.gitignore index 204f95a3..46313fc4 100644 --- a/standalone-openfl-app/.gitignore +++ b/standalone-openfl-app/.gitignore @@ -1,2 +1,9 @@ +**/bin/* +**/Export/* +**/lime-repo/**/* +**/openfl-repo/**/* + bin -Export \ No newline at end of file +Export +lime-repo +openfl-repo \ No newline at end of file diff --git a/standalone-openfl-app/CORE_PRINCIPLES_IMPORTANT!.md b/standalone-openfl-app/CORE_PRINCIPLES_IMPORTANT!.md index 3c236549..5d43579b 100644 --- a/standalone-openfl-app/CORE_PRINCIPLES_IMPORTANT!.md +++ b/standalone-openfl-app/CORE_PRINCIPLES_IMPORTANT!.md @@ -2,4 +2,22 @@ - Make the code work with the .hxml based workflow - don't use compiletime `#if lime` or `#if openfl` as this relies on the openfl and lime build system. We don't use their buildsystems but try to do the same thing they do for the hxcpp based targets. (Native Windows/ Linux compilation) - Adhere to the spec outlined in OpenFL_Build_Chain_Asset_System_Deep_dive.md and IMPORTANT_INSTRUCTIONS.md - \ No newline at end of file + - There is sample code in the Export/haxe directory. We want our own src/ManifestResources.hx to mirror the implementation in Export/haxe/ManifestResources.hx + - Mirror preload logic from the Export/haxe directory into our own files. + - We also want to preload our assets using a similar approach using the ManifestResource and doing related initialization in ApplicationMain.hx + +# Implementation details: + + - macros/AssetMacro.hx + - Implement a @:assets decorator that allows specifying assets with the same parameters that openfl/lime use in project.xml + - These assets will be defined in Assets.hx + - Generate an asset manifest `default.json` in a folder `manifest` in the hxcpp output directory (the same path the built binary gets put into) (get the path for this from the haxe compiler at build time) as defined with the `-cpp` flag in build.hxml + - Copy assets into the hxcpp output directory similarly to how lime and openfl do this + - Assets.hx + - as stated previously, the @:asset decorator will be used here to specify assets for the compiler to copy to the build output directory at compile time + - Main.hx + - This is the entrypoint for game specific code, no need to touch this yet. + - ApplicationMain.hx + - This is the actual entrypoint of the application. This sets up the lime/openfl application, window and stage. Also this is responsible for preloading assets. + - ManifestResources.hx + - This will be left the same as the sample in Export/haxe/ManifestResources.hx diff --git a/standalone-openfl-app/IMPORTANT_INSTRUCTIONS.md b/standalone-openfl-app/IMPORTANT_INSTRUCTIONS.md index 6dcb57f8..2038a922 100644 --- a/standalone-openfl-app/IMPORTANT_INSTRUCTIONS.md +++ b/standalone-openfl-app/IMPORTANT_INSTRUCTIONS.md @@ -19,4 +19,19 @@ We already know that it makes some calls to lime under the hood which has a simi The current project is built to create an openfl app using the hxml build system and bypass lime's/ openfl's build system entirely. -We are currently working on asset bundling, this is proving to be a difficult task. Please document how openfl does this in a file called BUILD_CHAIN_DOCUMENTATION_OPENFL.md \ No newline at end of file +We are currently working on asset bundling, this is proving to be a difficult task. Please document how openfl does this in a file called OpenFL_Build_Chain_Asset_System_Deep_Dive.md + +## What we need: +- `src/Assets.hx` + - define asset paths in a similar way to how openfl does this in the project.xml file. This will be done using a custom meta tag `@:Assets` + - We will have a macro in `src/macros/AssetMacro.hx` to process these meta tags, build a manifest, and copy the assets into the `--cpp` output directory specified in `build.hxml` +- `src/macros/AssetMacro.hx` + - Process `@:Assets` metatags defined in `src/Assets.hx` + - Build manifest in a `manifest` subdirectory the `--cpp` output directory specified in `build.hxml` + - copy the assets into the `assets` subdirectory in the `--cpp` output directory +- `src/ManifestResources.hx` + - initialize the Asset Libraries from the manifest files +- `src/ApplicationMain.hx` + - Initialize `src/ManifestResources.hx` + - bootstrap the openfl application + - add `src/Main.hx` to the application \ No newline at end of file diff --git a/standalone-openfl-app/LIME_PROJECT_FORMAT.md b/standalone-openfl-app/LIME_PROJECT_FORMAT.md new file mode 100644 index 00000000..a2c86949 --- /dev/null +++ b/standalone-openfl-app/LIME_PROJECT_FORMAT.md @@ -0,0 +1,734 @@ +--- +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 `