Using Precompiled Scripts
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.
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
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.
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.
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
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.