Using Precompiled Scripts

Functionality

Normally, when the engine starts up the angelscript plugin will read all .as files in your Project's script folder and parse and compile them. This can take a relatively long amount of time, especially on platforms with slower CPUs and hard drives.

In order to improve startup time in packaged builds, it is possible to instruct the packaged binary to emit a precompiled script cache. When a precompiled script cache file is present, the plugin will load the compiled script bytecode directly from the cache, skipping the need to load, parse and compile all the script files.

In addition to this, the plugin is able to generate a directory of C++ code files that function the same as the angelscript bytecode for your scripts. Recompiling the game binary with these C++ files included in it will then hook into angelscript's JIT compilation system to replace virtual machine bytecode execution with native C++. This significantly improves runtime execution speed of script code.

Usage

Precompiled script must be generated by the same .exe binary that it will be loaded by.

To trigger the generation:

• Package your game in the configuration you want to run.
• Run your ProjectName.exe while specifying the -as-generate-precompiled-data command line parameter.

This generates a file ProjectName/Script/PrecompiledScript.Cache that should be part of your game distribution.

The next time you run your packaged game, script will be loaded from the precompiled cache instead of from the .as scripts.

Transpiled C++ Code

In addition to the cache, the generate step will also output a folder called AS_JITTED_CODE/ with a file in it for every script file that was compiled.

You can copy this folder into your project's source folder and then rebuild the .exe for your game in the appropriate configuration.

When including the AS_JITTED_CODE/ folder in your project ensure that the module that it's being included it has AngelscriptCode as a dependency, i.e. within your project's Build.cs file.

Using the new .exe compiled with the included AS_JITTED_CODE/ and in combination with the PrecompiledScript.Cache file will let the angelscript plugin automatically run the correct optimized C++ code when executing angelscript.

Compatibility

Because precompiled scripts directly contain hardcoded byte offsets to C++ properties and sizes of C++ structures, you should never use a PrecompiledScript.Cache file that was generated by a different binary than it is being used by.

Whenever you rebuild your game's packaged .exe, always regenerate the precompiled script cache from that .exe. (The necessary exception of course being the rebuild when you add the generated C++ code to the binary)

The inverse is not necessary: it is possible to change the .as script files and generate a new PrecompiledScript.Cache without recompiling the game binary. If the old binary contained generated C++ code, it will no longer match the precompiled script cache and will not be used until the binary is rebuilt with the new AS_JITTED_CODE.

Reloading Scripts

When using a PrecompiledScript.Cache file, the actual .as script files are not loaded from the script folder. This means changes to those files will not be used, and hot reload is disabled.

In order to circumvent loading precompiled scripts when they are present, you can pass the -as-development-mode command line parameter to your packaged game binary.