From f06ee78988fb7e758660545cc574f2aededfb4ed Mon Sep 17 00:00:00 2001 From: ACrazyTown <47027981+ACrazyTown@users.noreply.github.com> Date: Thu, 18 Jun 2026 13:06:22 +0200 Subject: [PATCH 1/9] Update flixel-integration to use Lime 8.4's preupdate tag --- examples/flixel-integration/.gitignore | 1 + examples/flixel-integration/GeneratePak.hx | 5 +++-- examples/flixel-integration/Project.xml | 17 +++++++++++------ 3 files changed, 15 insertions(+), 8 deletions(-) create mode 100644 examples/flixel-integration/.gitignore diff --git a/examples/flixel-integration/.gitignore b/examples/flixel-integration/.gitignore new file mode 100644 index 0000000..a6debb2 --- /dev/null +++ b/examples/flixel-integration/.gitignore @@ -0,0 +1 @@ +paks/ diff --git a/examples/flixel-integration/GeneratePak.hx b/examples/flixel-integration/GeneratePak.hx index 597d967..86d88e5 100644 --- a/examples/flixel-integration/GeneratePak.hx +++ b/examples/flixel-integration/GeneratePak.hx @@ -12,7 +12,8 @@ class GeneratePak writer.addDirectoryRecursive("../assets/", null, ZIP); final bytes = writer.write(); - // TODO: unhardcode path - File.saveBytes("export/hl/bin/assets.pak", bytes); + // 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); } } diff --git a/examples/flixel-integration/Project.xml b/examples/flixel-integration/Project.xml index b6a3857..3b53f32 100644 --- a/examples/flixel-integration/Project.xml +++ b/examples/flixel-integration/Project.xml @@ -1,7 +1,7 @@ - - + + @@ -32,6 +32,13 @@ + + + + + + + @@ -47,9 +54,7 @@ - - - + From 4a77689a22aae814fed395f9cc197dbc4787a306 Mon Sep 17 00:00:00 2001 From: ACrazyTown <47027981+ACrazyTown@users.noreply.github.com> Date: Thu, 18 Jun 2026 13:24:33 +0200 Subject: [PATCH 2/9] oops fix --- examples/flixel-integration/Project.xml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/examples/flixel-integration/Project.xml b/examples/flixel-integration/Project.xml index 3b53f32..65a77aa 100644 --- a/examples/flixel-integration/Project.xml +++ b/examples/flixel-integration/Project.xml @@ -32,12 +32,10 @@ - - - + From 7c67a2b5dc967e8fcb1b7e1619f4fe6b07d1cfc6 Mon Sep 17 00:00:00 2001 From: ACrazyTown <47027981+ACrazyTown@users.noreply.github.com> Date: Thu, 18 Jun 2026 15:30:03 +0200 Subject: [PATCH 3/9] another test I forgot to remove --- examples/flixel-integration/Project.xml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/examples/flixel-integration/Project.xml b/examples/flixel-integration/Project.xml index 3b53f32..4547b5d 100644 --- a/examples/flixel-integration/Project.xml +++ b/examples/flixel-integration/Project.xml @@ -1,7 +1,6 @@ - - + From 7cf7b25bf767771572c40747fc479d2153444724 Mon Sep 17 00:00:00 2001 From: ACrazyTown <47027981+ACrazyTown@users.noreply.github.com> Date: Mon, 29 Jun 2026 16:51:26 +0200 Subject: [PATCH 4/9] Use hxp for generating paks --- README.md | 21 ++------ .../flixel-integration/.vscode/settings.json | 5 +- examples/flixel-integration/GeneratePak.hx | 19 ------- examples/flixel-integration/Project.xml | 5 -- examples/flixel-integration/README.md | 50 +++++++++++++++++++ examples/flixel-integration/gen.hxml | 3 -- examples/flixel-integration/project.hxp | 48 ++++++++++++++++++ 7 files changed, 105 insertions(+), 46 deletions(-) delete mode 100644 examples/flixel-integration/GeneratePak.hx create mode 100644 examples/flixel-integration/README.md delete mode 100644 examples/flixel-integration/gen.hxml create mode 100644 examples/flixel-integration/project.hxp diff --git a/README.md b/README.md index 71bf7e8..64ff29b 100644 --- a/README.md +++ b/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 `` 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 `` 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 diff --git a/examples/flixel-integration/.vscode/settings.json b/examples/flixel-integration/.vscode/settings.json index d0535ae..6999a80 100644 --- a/examples/flixel-integration/.vscode/settings.json +++ b/examples/flixel-integration/.vscode/settings.json @@ -10,5 +10,8 @@ "source.sortImports": "explicit" } }, - "haxe.enableExtendedIndentation": true + "haxe.enableExtendedIndentation": true, + "files.associations": { + "*.hxp": "haxe" + } } diff --git a/examples/flixel-integration/GeneratePak.hx b/examples/flixel-integration/GeneratePak.hx deleted file mode 100644 index 86d88e5..0000000 --- a/examples/flixel-integration/GeneratePak.hx +++ /dev/null @@ -1,19 +0,0 @@ -package; - -import antpak.Writer; -import sys.io.File; - -// Used to build our assets into a PAK and move it to the game export folder. -class GeneratePak -{ - static function main():Void - { - 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); - } -} diff --git a/examples/flixel-integration/Project.xml b/examples/flixel-integration/Project.xml index 4d3610d..6705da1 100644 --- a/examples/flixel-integration/Project.xml +++ b/examples/flixel-integration/Project.xml @@ -31,11 +31,6 @@ - - - - - diff --git a/examples/flixel-integration/README.md b/examples/flixel-integration/README.md new file mode 100644 index 0000000..051acb3 --- /dev/null +++ b/examples/flixel-integration/README.md @@ -0,0 +1,50 @@ +# Integrating antpak with HaxeFlixel projects +(also applicable to Lime/OpenFL... to an extent) + +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. + +## Generating the PAKs +### If you're using Project.xml: +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 `` 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 + +This is the part that's HaxeFlixel only, for now... sorry! + +After the game builds with the PAKs included, call +```haxe +antpak.integration.FlxPakAssets.init(); +``` +somewhere in your code, before any calls to `FlxG.assets` are made! + +`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! diff --git a/examples/flixel-integration/gen.hxml b/examples/flixel-integration/gen.hxml deleted file mode 100644 index 7a8899e..0000000 --- a/examples/flixel-integration/gen.hxml +++ /dev/null @@ -1,3 +0,0 @@ ---main GeneratePak --L antpak ---interp diff --git a/examples/flixel-integration/project.hxp b/examples/flixel-integration/project.hxp new file mode 100644 index 0000000..8296883 --- /dev/null +++ b/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", ""); + } +} From e314394d1af713a3765bd281cfc5c5e592a451df Mon Sep 17 00:00:00 2001 From: ACrazyTown <47027981+ACrazyTown@users.noreply.github.com> Date: Mon, 29 Jun 2026 16:53:18 +0200 Subject: [PATCH 5/9] copy relative path trolling --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 64ff29b..0e32f1e 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ Also wait it's still a work in progress so you probably shouldn't use it, also w ## Integration with frameworks See: -- [HaxeFlixel](examples\flixel-integration\README.md) +- [HaxeFlixel](examples/flixel-integration/README.md) ## TODO - [ ] Polish up API From f546ca3431b90ec292fd99d4741938a36e5fdb6d Mon Sep 17 00:00:00 2001 From: ACrazyTown <47027981+ACrazyTown@users.noreply.github.com> Date: Mon, 29 Jun 2026 16:55:39 +0200 Subject: [PATCH 6/9] fix hxp? --- examples/flixel-integration/.gitattributes | 1 + 1 file changed, 1 insertion(+) create mode 100644 examples/flixel-integration/.gitattributes diff --git a/examples/flixel-integration/.gitattributes b/examples/flixel-integration/.gitattributes new file mode 100644 index 0000000..c57a3ec --- /dev/null +++ b/examples/flixel-integration/.gitattributes @@ -0,0 +1 @@ +*.hxp linguist-language=Haxe From 264fe407fd733b3b32e0b9b81f4002a108f74532 Mon Sep 17 00:00:00 2001 From: ACrazyTown <47027981+ACrazyTown@users.noreply.github.com> Date: Mon, 29 Jun 2026 16:56:00 +0200 Subject: [PATCH 7/9] Nvm --- examples/flixel-integration/.gitattributes => .gitattributes | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename examples/flixel-integration/.gitattributes => .gitattributes (100%) diff --git a/examples/flixel-integration/.gitattributes b/.gitattributes similarity index 100% rename from examples/flixel-integration/.gitattributes rename to .gitattributes From 5c92bc327fa55253a600e17cf1214a3f2af092ab Mon Sep 17 00:00:00 2001 From: ACrazyTown <47027981+ACrazyTown@users.noreply.github.com> Date: Mon, 29 Jun 2026 17:01:12 +0200 Subject: [PATCH 8/9] docccssssssssss --- examples/flixel-integration/README.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/examples/flixel-integration/README.md b/examples/flixel-integration/README.md index 051acb3..eabe8ed 100644 --- a/examples/flixel-integration/README.md +++ b/examples/flixel-integration/README.md @@ -8,6 +8,8 @@ The example project generates a single PAK file from the `assets/` directory in > [!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: Copy over [`project.hxp`](project.hxp) to the root of your project, next to Project.xml. @@ -36,11 +38,14 @@ Copy over the `createAssetsPak()` method from the example hxp file. You should c This is the part that's HaxeFlixel only, for now... sorry! -After the game builds with the PAKs included, call +Make sure you've included the `antpak` library into your project! +- `` 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(); ``` -somewhere in your code, before any calls to `FlxG.assets` are made! `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. From 8f92da43445cf5e7549f6a61bf5d1a2cd654ff0e Mon Sep 17 00:00:00 2001 From: ACrazyTown <47027981+ACrazyTown@users.noreply.github.com> Date: Mon, 29 Jun 2026 17:07:04 +0200 Subject: [PATCH 9/9] note --- examples/flixel-integration/README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/examples/flixel-integration/README.md b/examples/flixel-integration/README.md index eabe8ed..e5eb265 100644 --- a/examples/flixel-integration/README.md +++ b/examples/flixel-integration/README.md @@ -12,6 +12,9 @@ First things first, make sure you've installed the `antpak` library: `haxelib gi ## 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.