Documentation for AssetPaths

default/source/AssetPaths.hx

@@ -1,4 +1,95 @@
 package;
 
+/**
+	Helper class to access asset paths in a type-safe manner. 
+
+	`AssetPaths`'s static fields are autogenerated by a neat [Haxe macro](http://haxe.org/manual/macro.html) 
+	from the contents of Project.xml's `<assets>` tag, so you can easily reference them in your code:
+
+	```haxe
+	// Play sound effect using AssetPaths
+	FlxG.sound.play(AssetPaths.mySound__wav);
+	// instead of using string path
+	FlxG.sound.play("assets/sounds/mySound.wav");
+	```
+
+	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. You will get a warning at compile time when:
+
+	- File names do not match Haxe valid id pattern, e.g. starting with a digit.
+
+		A file `assets/1.ogg` won't appear on `AssetPaths` since you cannot do `AssetPaths.1__ogg` in Haxe.
+		If you don't want to rename the file you have to use it as a string.
+
+		```haxe
+		FlxG.sound.play("assets/1.ogg");
+
+		// this wont work
+		// FlxG.sound.play(AssetPaths.1__ogg);
+		// assets/1.ogg:1: character 1 : Warning : Invalid name: 1__ogg for file: assets/1.ogg
+		```
+
+	- Duplicate file names.
+
+		If you have assets with the same file names, whichever file is nested deeper or found later 
+		will be ignored.
+
+		```haxe
+		// assets folder:
+		// assets/music/hero.ogg
+		// assets/sounds/hero.ogg
+
+		// prints "assets/music/hero.ogg"
+		trace(AssetPaths.hero__ogg);
+		// assets/sounds/hero.ogg:1: character 1 : Warning : Duplicate files named "hero__ogg" ignoring assets/sounds/hero.ogg
+		```
+
+	## More control
+
+	`AssetPaths` uses [`flixel.system.FlxAssets.buildFileReferences`](https://api.haxeflixel.com/flixel/system/FlxAssets.html#buildFileReferences). The method provides you some control on what and how 
+	`AssetPaths`'s fields are built. Check its documentation for more details.
+
+	### Include and exclude
+
+	These args can either be an `EReg`, or a wildcard string, similar to openfl's `project.xml args`. 
+	For example to exclude everything in a folder called "test", as well as any .ase files, 
+	you would use `~/\/test\/|\.ase/`.
+
+	```haxe
+	@:build(flixel.system.FlxAssets.buildFileReferences("assets", true, null, ~/\/test\/|\.ase/))
+	class AssetPaths {}
+	```
+
+	### Renaming
+
+	You can provide `rename` function, e.g. to deal with duplicate names. The function takes a filepath 
+	(a relative filepath from the `Project.xml`) and returns a field name used to access that path. 
+	Returning `null` means "ignore the file".
+
+	```haxe
+	// assets structure:
+	// assets/music/hero.ogg
+	// assets/sounds/hero.ogg
+
+	// AssetPaths.hx
+	@:build(flixel.system.FlxAssets.buildFileReferences("assets", true, null, null, function(name:String):Null<String> {
+	return name.toLowerCase()
+					.split("/").join("_")
+					.split("-").join("_")
+					.split(" ").join("_")
+					.split(".").join("__");
+	}))
+	class AssetPaths {}
+
+	// somewhere in your code
+	FlxG.sound.play(AssetPaths.assets_music_hero__ogg);
+	FlxG.sound.play(AssetPaths.assets_sounds_hero__ogg);
+	```
+**/
 @:build(flixel.system.FlxAssets.buildFileReferences("assets", true))
 class AssetPaths {}