Better integration with Lime 8.4.0

.gitattributes

@@ -0,0 +1 @@
+*.hxp linguist-language=Haxe

README.md

@@ -6,25 +6,10 @@ An `antpak` is a custom implementation of a PAK file archive format. This librar
 
 Also wait it's still a work in progress so you probably shouldn't use it, also wait I made it cause I was bored so no guarantees I'll keep working on it heehee !
 
-## Integration with other libraries
-### HaxeFlixel
-Integration with HaxeFlixel is really simple. All you need to do is call `FlxPakAssets.init()` somewhere, before using any methods that rely on `FlxG.assets`. This is usually in `Main.hx` or some sort of init state. After that, mount your PAKs and use HaxeFlixel as usual. 
+## Integration with frameworks
 
-For convenience you'd ideally want a way to automatically build the pak with the game. This can be accomplished using the `<postbuild>` tag in Project.xml and an additional Haxe script. See the [Flixel example](/examples/flixel-integration) for specifics, or follow these general steps:
-1. Install the library via `haxelib git antpak https://github.com/ACrazyTown/antpak`
-2. Copy over [`GeneratePak`](/examples/flixel-integration/GeneratePak.hx) and [`gen.hxml`](/examples/flixel-integration/gen.hxml) to your top folder. You will have to adjust some of the parameters in the script according to your project.
-3. Add `<postbuild cmd="haxe gen.hxml"></postbuild>` somewhere in your Project.xml.
-4. In your game code, add `FlxPakAssets.init()` somewhere, before any attempts to fetch assets, otherwise you won't be able to fetch assets from PAKs.
-5. Mount your PAK using `Pak.mount(path);`
-6. Profit
-
-> [!WARNING]
-> `FlxPakAssets` hooks into the dynamic functions provided by `FlxG.assets`. If your or another library's code also tries to hook into these functions, issues may occur.
-
-The asset system first checks if the wanted asset is available in the PAK, and then queries Flixel's default asset system if it isn't.
-
-> [!WARNING]
-> Due to how PAKs work, it is not possible to query an asset based on its asset type. When requesting an asset, it will attempt to convert itself into the requested type. Ensure you are requesting the right file and type to avoid any unforeseen consequences.
+See:
+- [HaxeFlixel](examples/flixel-integration/README.md)
 
 ## TODO
 - [ ] Polish up API

examples/flixel-integration/.gitignore

@@ -0,0 +1 @@
+paks/

examples/flixel-integration/.vscode/settings.json

@@ -10,5 +10,8 @@
 			"source.sortImports": "explicit"
 		}
 	},
-	"haxe.enableExtendedIndentation": true
+	"haxe.enableExtendedIndentation": true,
+	"files.associations": {
+		"*.hxp": "haxe"
+	}
 }

examples/flixel-integration/Project.xml

@@ -1,7 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <project xmlns="http://lime.openfl.org/project/1.0.4" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 	xsi:schemaLocation="http://lime.openfl.org/project/1.0.4 http://lime.openfl.org/xsd/project-1.0.4.xsd">
-
 	<!-- _________________________ Application Settings _________________________ -->
 
 	<app title="antpak Flixel Integration" file="antpak-flixel-integration" main="Main" version="0.0.1" company="ACrazyTown" />
@@ -47,9 +46,7 @@
 	<!--<haxelib name="nape-haxe4" />-->
 
 	<!-- ______________________________ Haxedefines _____________________________ -->
-
-	<!-- TODO: surely there's a better way to do this than invoking a seperate hxml ? -->
-	<postbuild cmd="haxe gen.hxml"></postbuild>
+
 	<haxedef name="FLX_NO_SAVE" />
 
 	<!--Remove the legacy health system-->

examples/flixel-integration/README.md

@@ -0,0 +1,58 @@
+# Integrating antpak with HaxeFlixel projects 
+<sup>(also applicable to Lime/OpenFL... to an extent)<sup>
+
+This project is provided as an example, which you should expect to have to modify according to your use case. The steps in the source files are documented, which should hopefully make this process a bit easier to understand.
+
+The example project generates a single PAK file from the `assets/` directory in the folder above.
+
+> [!NOTE]
+> Due to current limitations, PAKs do not have an associated asset type. For example, if you try to query a list of assets with the `MUSIC` type, you will instead get a list of all assets in the PAK. You can work around this by filtering based on the file extension.
+
+First things first, make sure you've installed the `antpak` library: `haxelib git antpak https://github.com/ACrazyTown/antpak`.
+
+## Generating the PAKs
+### If you're using Project.xml:
+> [!IMPORTANT]
+> This **requires** Lime 8.4.0+ as it fixes an issue which stops you from compiling the game when you combine HXP and XML projects.
+
+Copy over [`project.hxp`](project.hxp) to the root of your project, next to Project.xml.
+The [HXP format](https://lime.openfl.org/docs/project-files/hxp-format/) is essentially the same thing as Project.xml but written using Haxe. It is prioritized above XML and therefore will run before it. We use this to our advantage to run a script that generates the PAK file(s) and tells Lime to copy them over to the export directory, before running the Project.xml.
+
+> [!IMPORTANT]
+> In your Project.xml, **make sure** to get rid of any `<assets />` tags that reference the same assets as the PAK, otherwise you're going to have **both** the PAK and the copied (or embedded) files in your game.
+
+### If you're using Project.hxp:
+Like above, you'll reference the included [`project.hxp`](project.hxp) file here. Though you can't copy it in its entirety, you'll need to copy over certain bits.
+
+Next to the class declaration, you **must** include the following metadata like so: 
+```haxe
+@:compiler("-lib")
+@:compiler("antpak")
+class Project extends HXProject {...}
+```
+This tells HXP to include `antpak` when running the script, which makes it possible for us to call the required methods needed to generate PAKs.
+
+Copy over the `createAssetsPak()` method from the example hxp file. You should call it sometime before processing assets. 
+
+> [!IMPORTANT]
+> Like with Project.xml based projects, **make sure** to get rid of any code that references the same assets as the PAK, otherwise you're going to have **both** the PAK and the copied (or embedded) files in your game
+
+## Actually using them
+
+<sup>This is the part that's HaxeFlixel only, for now... sorry!</sup>
+
+Make sure you've included the `antpak` library into your project!
+- `<haxelib name="antpak" />` if you're using Project.xml
+- `haxelibs.push(new Haxelib("antpak"))` if you're using Project.hxp
+
+In your project's source code, before any calls to `FlxG.assets` are made, call
+```haxe
+antpak.integration.FlxPakAssets.init();
+```
+
+`FlxPakAssets` hijacks the `FlxG.assets` method with its own custom methods, which first check if the wanted asset is available in any of the mounted PAKs, before falling back to the original methods. 
+
+> [!NOTE]
+> If you're using any other libraries (or hijacking `FlxG.assets` yourself), you should make sure to init `FlxPakAssets` last, after that.
+
+Finally, mount your PAKs via `antpak.Pak.mount(path);` and you're good to go!

examples/flixel-integration/project.hxp

@@ -0,0 +1,48 @@
+import hxp.*;
+import lime.tools.HXProject;
+import lime.tools.ProjectXMLParser;
+import sys.FileSystem;
+import sys.io.File;
+import antpak.Writer;
+
+// IMPORTANT: Tell HXP to include antpak as an accessible library
+@:compiler("-lib")
+@:compiler("antpak")
+class Project extends HXProject
+{
+    public function new()
+    {
+        super();
+
+        // Generate our PAKs
+        createAssetsPak();
+
+        // After our work is done, run the Project.xml! 
+        merge(new ProjectXMLParser("Project.xml"));
+    }
+
+    /**
+     * Generates .pak files from the assets directory, and tells Lime
+     * to copy them over to the export directory.
+     */
+    function createAssetsPak()
+    {
+        // Create our paks directory where we'll store pak files until
+        // they get copied over to the export directory.
+        if (!FileSystem.exists("paks"))
+            FileSystem.createDirectory("paks");
+
+        // Here we're going to generate a single PAK made from contents in the assets directory. 
+        var writer:Writer = new Writer();
+        writer.addDirectoryRecursive("../assets/", null, ZIP);
+        final bytes = writer.write();
+
+        // Write our PAK to a temporary paks/ folder in the root,
+        // from where it will be later copied to the export directory
+        File.saveBytes("paks/assets.pak", bytes);
+
+        // Tell Lime to include all of the paks in the paks directory, but rename them
+        // so they get copied in the root, right next to the executable
+        includeAssets("paks", "");
+    }
+}