Faster compiler iteration with cppia - proletariatgames/unreal.hx GitHub Wiki

Unreal.hx is powered by Haxe's C++ target (hxcpp). Because of that, compilation times aren't faster than Unreal's own compilation, and because of the glue code generated, it can be even slower.

In order to improve compilation times, unreal.hx supports cppia (pronounced sepia) - which is a small virtual machine built into hxcpp, and completely compatible with it. With cppia, one can extend native hxcpp types, implement native hxcpp interfaces, and do pratically anything that you could do with hxcpp. For more information about cppia, see this presentation about it. With it enabled, compilation times are greatly enhanced, and are normally just a couple of seconds.

Setting up

Cppia is enabled by default on any unreal.hx project. When unreal.hx is installed on a new project, two directories are created on the root /Haxe directory: Static and Scripts. By default, any game code inside Static will be statically compiled (as C++ in hxcpp), and any code inside Scripts will be compiled by cppia - unless this is a build which is being compiled without the Unreal Editor support. This behavior can be changed in various manners which will be explained in a later section.

When adding new UObject-derived classes, or adding/renaming @:uexpose functions or native C++ function overrides, or creating or changing new UENUMs or USTRUCTs on the Haxe side, you must perform a recompilation of the C++ code before the class and the new fields are available for you to use. Once you have compiled statically, you can then iterate quickly without performing a C++ compilation by using the gen-build-script.hxml file (ie by calling haxe gen-build-script.hxml from the command-line). If you have your editor open, the editor will watch for compilations and automatically reload the scripts. Note that haxe gen-build-script.hxml will fail if a full C++ compilation is detected.

Limitations and remarks

  • Cppia classes cannot replace already statically compiled classes. Because of this limitation, classes in /Static cannot reference classes in /Scripts. Classes in /Scripts, however, can reference and extend classes in /Static.

Watch out that this limitation is only enforced by the Haxe compiler for source files that are in the /Static folder. If you add another classpaths, and a Static type refers to a type in that classpath, and that type makes references to a script, Haxe compilation might succeed, but the C++ compilation will fail. So beware!

  • Cppia sometimes cannot compile some code that can runs on hxcpp. If your code uses unsafe constructs (e.g. cpp.Pointer or accesses non-hxcpp native code, it cannot run in cppia

  • Cppia is only active if it's not a standalone build. This cannot be changed for now.

  • Structs or delegates will always be compiled as static

Changing the default behaviour

You can change the default behaviour of what can be compiled as static code, and what can be compiled as a script. You can provide an extra json file called uhxconfig.local (at the root of the project, as a sibling to your .uproject), with the following options:

  • noStatic : true: will compile everything - both Static and Script as a cppia module. Good for iterating on code that is already set to compile as Static. You can further selectively compile some classes as static - even with this flag - by adding the @:ustatic metadata to the class

  • disableCppia : true: will disable cppia and compile everything as static code. This behaviour will also always happen on non-editor builds