Using Precompiled Data

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 relative long amount of time, especially on platforms with slower CPUs and hard drives.

In order to improve startup time in packade 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 the compiled script. 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.

In addition, the generate step will 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.

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. This works even if that old binary contains generated C++ code.

The angelscript plugin will automatically detect when the script code it is using is different from the code that was compiled into AS_JITTED_CODE/ and only uses the generated C++ code for functions where the script matches.

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 this at the cost of somewhat reduced startup performance, pass the -as-development-mode command line parameter to your packages game binary.

In development mode, generated C++ code will still be used for files where the script has not changed since precompiled data was generated. However, changes to script files are automatically detected and recompiled.