An Unofficial Heaps FAQ

heapsfaq.md

An Unofficial Heaps FAQ

I (Yanrishatum) see too many same questions. They irritate me.

Translation

"How dare you come into this chat and not realize that i am the GOD of heaps and that you MUST check out MY documentation1!!! Im veyr abngrey!!!" - translation from someone in chat.

Very accurate, I highly approve.

Changelogs

27/03/20: Added extended FAQ.
20/06/20: Altered window resizing info (suggested by TitForTat#1234 ).
23/06/20: [FAQ2] Added help about HIDE prefab loading. (Thanks TitForTat#1234 and jefvel#3150 ) 29/10/21: Removed outdated questions (4.2 haxe crash/2d camera), updated some questions, added some questions, added Official™ translation of what header statement actually means. Very accurate.

Use git Heaps, haxelib version is always outdated, especially if you use Haxe 4.1+

Q: I've just installed Heaps 1.8.0 (or whatever haxelib version is right now) and don't see features people talk about in chat!

A: Use git heaps. It's pretty stable. You can do that with haxelib git heaps https://github.com/HeapsIO/heaps.git. Note that new versions of Heaps do not support Haxe3, and require Haxe4.

Q: Can I compile it with HXCPP/Lime/OpenFL/Kha?

A: No. Heaps does not support any of those backends. Only Hashlink (+HLC), HTML5 and flash are supported.

Q: But it says on Heaps.io that I can publish on all major platforms!

A: Yes, you can, by using HLC. But it won't be a smooth sailing if it's not HTML5 or desktop. Hit up Heaps devs for console backends with proofs of having SDK license, and for mobile see below.

Q: Can I compile it on Android/iOS?

A: In theory. There's no established pipeline to do so, and if someone succeeded - he didn't really share it with community. You can find outdated project files for android here

Q: How do I compile an exe file?

A: Use Hashlink to generate C source code, then proceed with compiling it with your compiler of choice. Here is a separate guide on compilation and alternative approaches: How to compile HL/C

For reference: Northgard and Darskburg bundle bytecode version with VM, and HL/C used only for consoles.

Q: Where is an update on Objects?

A: Heaps does not come with update loop for objects, it's up to you to implement it. Closest thing to update is sync, which you shouldn't treat as such - it should be used to sync data such as position matrix and other parameters that are used for rendering. There is an update method in hxd.App.

Q: Physics?

A: Heaps does not come with a physics simulation nor collision detection system. It's primarily focuses on rendering. There are very basic collision classes in h2d.col and h3d.col, but by default they are used for hit-testing against mouse. There are physics and collision detection libraries on haxelib. For example nape, differ, echo

Q: There's so little documentation!

A: Deal with it. Practically nobody contributes to documentation. There is some. There also samples in samples (duh) folder (also see question below regarding more samples). You're always welcome to provide documentation on things. ¯\_(ツ)_/¯

Q: I'm targeting HTLM5 and my JS file is way too big!

A: It's because you used Res.initEmbed. As name suggests, it embeds all resources into the code/binary. On JS it results in base64-encoded files as raw strings in JS file. For JS it's recommended to use pak file system or implement your own FS

Q: How do I produce a pak file?

A: See Resource Management in docs.

Q: My MP3 file does not show in Res on Hashlink!

A: MP3 in Res is specifically disabled on Hashlink due to it being inferior to OGG. However if you use it for whatever reason, you can enable it with -D heaps_enable_hl_mp3 in hxml file. It is still possible to load and play MP3 files on HL without enabling them in Res. Do it via hxd.Res.load method.

Q: My OGG file does not show in Res / work on JS!

A: Due to the fact that not all browsers are capable of playing .ogg files (hello Apple), Heaps does not use native ogg decoder, hence does not support ogg files on JS unless you add stb_ogg_sound library.

Q: How do I set window title/size in HL?

A: At compile time, use following -D flags:

-D windowTitle=My Fancy Title
-D windowSize=800x600

At runtime:

@:privateAccess hxd.Window.getInstance().title = "My Fancy Title";
hxd.Window.getInstance().resize(800, 600);
// With `@:privateAccess` it's possible to access underlying Window instance
// This works only on DirectX or SDL
var win = @:privateAccess hxd.Window.getInstance().window;
win.center(); // Relocate window to center of the screen.
win.setMinSize(400, 300); // Set minimum possible size of the window.
win.setMaxSize(1024, 768); // Set maximum possible size of the window.
// It's also possible to modify window position and sizing separately trough it's poroperties.

Q: Game renders incorrectly on my high DPI screen, why?

A: This is due to high DPI support not being fully implemented, as well as old version of SDL being used. Current solution is to manually build HLSDL with newer SDL binaries, as it seem to fix it. See this comment for fix instructions.

Q: I've found a bug!

A: Report it here

Q: I want a feature!

A: Report it here but most likely you won't get it. Also maybe worth discussing it in discord channel.

Q: I have a question, but it isn't here!

A: Tune in to #Heaps channel in Haxe discord, it's the most active place. You also can try forums, but it's a wild card.
When asking a question about issue you have, please specify the following:

• Which target: HTML5, SDL or DirectX
• Specifically note if you are on high-DPI monitor.
• Which scene you are using: s2d or s3d
• In case of s3d - which material setup: Forward (default) or PBR

This will help a lot when trying to understand what problem you have, as we won't have to torture you for information if it's s2d or s3d on problems like "Collisions don't work properly", or realize that you have a DPI bug when your scene is rendered incorrectly.

Q: Are there any samples on how to do things?

A: Obviously a samples folder. There also full game samples page in documentation. You also can check out pinned messages in #Heaps channel on discord, there were some too.
Update 27/02/20: Keep an eye on DeepNight's tutorials section on his website, as he plans to write at least a few getting started tutorials. Update: 29/10/21: There's also a fairly old samples by Beeblerox. Not that they are outdated on a number of occasions, like camera sample, but still should give you a good showcase about various elements.

Q: What shaders does Heaps use?

A: Its own language - HXSL, which then compile into either GLSL or HLSL. It has a lot of limitations and peculiarities, so here's a cheat sheet about for shaders.

Q: Geometry shaders?

A: No.

Q: Is there a Vulkan/Metal backend?

A: No, but Cannasse works on Vulkan backend in his free time.

Q: Is there any libraries that make my life easier while using Heaps?

A: Yes.

• See DeepNight's gameBase and deepnightLibs.
• His LDtk also have support for heaps.
• My Heeps library.
• Consider using HIDE. But you're on your own in that regard, as barely anyone knows how to use it. There are nightly builds available.
• Also check out CastleDB (HIDE have it built-in)
• Found something else? Ping me up in Discord.

heapsfaq2.md

An Extended Unofficial Heaps FAQ

This one would cover more specific questions than entry-point FAQ, that I've seen more than once in chat and start to get irritated by seeing them over and over. I expect that you've read initial FAQ before going there.

Q: How do I add shaders?

A:

• For 3D - rendering uses pass system in order to render things. Hence you add shaders not to Materials, but to Pass instances. And most likely you want to add shader to main pass, which can be obtained with materials.mainPass. Method name is addShader. If you want to add shader to every created material - use custom MaterialSetup and override creation method in wchich you can add your global shader and configura materials in general.
• For 2D - Just use Object.addShader. Note that those shaders do not propagate to object children. For entire object tree use Object.filter and filters for that, but also be aware that each filter internally is being rendered onto temporary texture first, so it may add up a lot of cost to rendering.

Q: Why Res.initLocal does not work with HTML5?

A: Because local file system requires access to system file system. And HTML5 is not sys language (except if you use Nodejs). Also avoid using embed FS for shipping, it embeds your assets into the JS output file by encoding them with base64. Bad idea. Use pak filesystem or custom-made ones.

Q: How do I show 2D behind 3D?

A: Insert extra 2D scene to scene list before 3D scene. You can't easily interleave them unless you put your 2D stuff as 3D objects in 3D scene, because scenes are rendered in-order. By the way, you can write your own scene and render stuff however you want, you aren't limited to s2d/s3d.

Q: How do I integrate Tiled?

A: With libraries. Built-in support is shit, don't use it. For basic support you can this library, and if you want more control - use format-tiled library. Heeps also provides extra integration with format-tiled directly to Res.

Q: Gif support?

A: In short - no, use spritesheets. In long - gif format is very specific, and for built-in support, still requires internally expanding it to spritesheet. On top of that, gif uses variable frame times, and stock Heaps 2D animation systems are fixed frame times only. Heeps provides advanced animation systems. It also provides Res integration* of gif files.
*As of 27/03/20: Due to changes in Heaps convert system, gif integration is broken and requires manual registration of gif convert by adding "gif": "giff" convert to props.json (see below).

Q: What is props.json and why do I need it?

A: props.json is a file you put in your res folder and which is used by HIDE and some parts of Heaps. For Heaps - it can be used to register Converts. See Resource Baking in official wiki.

Q: My HIDE prefabs don't load properly!

A: Make sure you reference those prefab types somewhere in your project. For example, doing an import hrt.prefab.Model; in Main. This is required to ensure that those prefabs are registered in prefab library. Additionally, to apply renderProps, an extra step is required:

var renderProps = resource.getOpt(hrt.prefab.RenderProps, "defaults");
if( renderProps == null )
  renderProps = resource.getOpt(hrt.prefab.RenderProps);
if( renderProps != null )
  renderProps.applyProps(game.s3d.renderer);
else
  defaultRenderProps.applyProps(game.s3d.renderer);

Q: When I use --macro my.resource.Register.init() to register custom resources it stops compiling!

A: If you use import.hx feature - make sure you gate everything in it behind #if !macro, as it would get imported in your macro methods as well, and that will break stuff. In general make it a habit to gate import.hx stuff in such way.

For JS it's recommended to use pak file system or implement your own FS

I'd like to know how you've been using pak with JS, it appears JS support in the pak format is "TODO"

@moggers87
It's a TODO, because it's a synchronous API, and you can't do that on JS (i.e. load the file synchronously. in fact, I doubt it'll EVER become a non-todo). You first load the pak file via BinaryLoader (or any other way, as long as you turn it into Bytes) and then create pak FS to which you add the loaded, and then assign Res.loader = new Loader(pakFS);

In fact, I have a macro helper that would build the pak file and would load it asynchronously on JS and synchronously on native, calling the passed onReady.

I.e. to load pak on JS you do (very pseudocodish rough outliune):

var data = BinaryLoader.load("res/assets.pak");
// Following is done only after loader have the data, which is when it does `onLoaded`.
var pakFS = new hxd.fmt.pak.FileSystem();
pakFS.addPak(new hxd.fmt.pak.FileSystem.FileInput(data));
hxd.Res.loader = new hxd.res.Loader(pakFS);
// You're good to go - assets loaded

it is a little bit of a scam that they list mobile support and yet are unable to provide a working mobile example.