Using Precompiled Data
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.
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.exewhile specifying the
-as-generate-precompiled-datacommand 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
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.
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
(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
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.
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.