From 2290b3c3f8fb460ece10f1e1f056af63519dcbd2 Mon Sep 17 00:00:00 2001 From: Timur Date: Tue, 7 Mar 2023 02:51:31 +1000 Subject: [PATCH] Documentation for AssetPaths (#42) * Documentation for AssetPaths To address this https://github.com/HaxeFlixel/flixel-docs/issues/265 * Address review issues * address review issues remove "more control" (will be in other doc) add @see tags * a note about where is this class from * add left * * aork around vscode md issues, shorten --------- Co-authored-by: George FunBook --- default/source/AssetPaths.hx | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/default/source/AssetPaths.hx b/default/source/AssetPaths.hx index db7ef44..8d5f33b 100644 --- a/default/source/AssetPaths.hx +++ b/default/source/AssetPaths.hx @@ -1,4 +1,35 @@ package; +/** + * Helper class to access asset paths in a type-safe manner. + * + * **NOTE:** this class is created when you use [`flixel template` command](https://haxeflixel.com/documentation/hello-world/#create-a-new-haxeflixel-project). + * + * `AssetPaths`'s static fields are autogenerated by a neat [Haxe macro](http://haxe.org/manual/macro.html) + * from the contents of [Project.xml's ``](https://lime.openfl.org/docs/project-files/xml-format/#assets) + * tag, so you can easily reference them in your code. For example, rather than using the string path + * `"assets/sounds/mySound.wav"`, this class will generate `AssetPaths.mySound__wav` that you can pass into + * `FlxG.sound.play` calls. + * + * Static fields available on `AssetPaths` will change whenever you add, remove, rename or move a file. + * If you remove a file that is still referenced via `AssetPaths` you'll get a compile error, + * this could be handy compared to using string paths, which only cause a runtime error if the file is missing. + * + * ## Ignored Assets + * + * In some cases `AssetPaths` will ignore your assets. The following cases will result in a warning + * at compile: + * + * - **Invalid haxe fields**: For example, the file `assets/1.ogg` will give a warning since + * `1__ogg` is not a valid haxe field name. + * + * - **Duplicate file names**: If you have assets with the same file names, whichever file is nested + * deeper or found later will be ignored. for example if you have assets `assets/hero/walk.png` and + * `assets/enemies/ranger/walk.png`, the latter will be ignored and the compiler will show a warning. + * + * @see [FlxAssets.buildFileReferences()](https://api.haxeflixel.com/flixel/system/FlxAssets.html#buildFileReferences) is used by `AssetPaths` + * and provides you some control on how `AssetPaths`'s fields are built. + * @see [Flixel 5.0.0 Migration guide - AssetPaths has less caveats](https://github.com/HaxeFlixel/flixel/wiki/Flixel-5.0.0-Migration-guide#assetpaths-has-less-caveats-2575) +**/ @:build(flixel.system.FlxAssets.buildFileReferences("assets", true)) class AssetPaths {}