If I’m understanding the generated code and behavior that I’m observing correctly, here’s how it works:
@:bitmap() adds the asset data as a Haxe Resource. If you’re targeting html5, for instance, it gets included as a Base64-encoded string in the generated .js file.
On the other hand, <assets/> seems to always copy the asset as a separate file in the output directory. When you set embed="true", for the html5 target, the asset will be preloaded so that it will be available as soon as the code in your main class starts running. If embed="false", you need to ask for the asset to be loaded, and you can’t use it until the load completes.
With all this in mind, you will have two separate copies of the image.
Why is this different on html5 than other targets? With cpp, embed determines whether the file is an encoded string in the code, vs a file copied over. I’m assuming this because when i embed assets they do not appear in the exported asset folders. furthermore I’ve always used libraries’ preload attribute to determine whether an asset is loaded before the Main class is executed. Until now I’ve never used embed="true" for html and I’ve been able to use assets in the default library even without embedding and without manually loading them. I only need to manually load libraries if their preload is set to false
Edit: I removed the embed="true" tag from my include.xml assets and they still seem to be preloaded on html5
I didn’t write the OpenFL’s assets loading system, or the macro that is used with @:bitmap, so I’m just reading through the code and running some tests to try to answer your questions. I can’t say what the original author was thinking. However, from my perspective, if I didn’t know that there was a way to include encoded binary data in the generated .js file (Haxe Resources), then the most obvious way to ensure that an asset is available when the code from a project’s Haxe class starts running is to preload it beforehand.
the above behaves the same as <library name="transitions" preload="false"/>, I need to call loadLibrary, but with preload=“true” I do not. regardless of the value of embed on either the library or the asset
It seems that in html5 the embed attribute has no effect, whatsoever. Perhaps it was simply not implemented? The library’s preload attribute seems to be the sole determinant of whether a loadLibrary call is required to use the asset (tested on html5 and mac)
None of this is an issue for me, at the moment, just reporting my findings