Skip to main content

xIl2cpp Mode - Special Optimization Mode for Unity il2cpp

Available Version: >2.0.0

xIl2cpp mode is a new mode added in Puer2.0 version. As the name suggests, the optimization is only for Unity Il2cpp backend. The name xIl2cpp pays tribute to xLua, the predecessor of PuerTS, and represents the technology that enhances optimization based on Il2cpp.

In simple terms, xIl2cpp mode allows il2cpp to directly interact with v8, without going through C# PInvoke to call native plugins. This reduces cross-language consumption and ultimately greatly improves performance, as shown in xil2cpp mode performance data.

There will be significant changes in the way xIl2cpp mode is used, such as different steps for compiling plugins and wrappers, but there is no need to make any changes to the API and usage mechanism.

Installation​

If you decide to use xIl2cpp mode, it is currently recommended to use the GitHub Clone and Install with Unity UPM method mentioned in the installation guide. The repository address needs to be changed to https://github.com/Tencent/puerts.git, and the added path is [puerts]/unity/Assets/core/upm/package.json.

The reason why you need to clone the source code is that you need to compile Puer's binary plugin yourself to use the xIl2cpp capability.

Then, you need to first understand the content of the compilation guide. The compilation of the xIl2cpp version is slightly different but similar in general (for example, you no longer need to download the backend yourself).

Steps to Use​

  1. Install the PuerTS upm package according to the above steps.
  2. Compile the mono version plugin: cd to puer directory/unity/native_src/, enter the compilation command that matches your platform, such as node ../cli make --backend v8_9.4 --platform win --arch x64 --config Debug (the compilation command itself actually recognizes your platform, so you can also only enter node ../cli make --backend v8_9.4 --config Debug).
  3. Enter Unity's Player Settings and add two Scripting Define Symbols: PUERTS_CPP_OUTPUT_TO_NATIVE_SRC_UPM, EXPERIMENTAL_IL2CPP_PUERTS. You can also switch the script backend to il2cpp. Wait for the script to compile.
  4. Generate the code required for compilation: click Tools/PuerTS/Generate for xIl2cpp mode(All in One) in Unity. Then switch to cd to puer directory/unity/native_src_il2cpp, and enter the same compilation command as step 2.

Some Detailed Explanations in the Steps to Use​

  • Because we try to let v8 and il2cpp interact directly, the Wrapper in the il2cpp version is in the form of C++ rather than C#. The FunctionBridge.h generated by Generate for xIl2cpp mode plays the role of the original Static Wrapper.
  • FunctionBridge.h currently needs to be compiled into nativePlugins, so xIl2cpp mode requires you to frequently compile native plugins yourself.
  • Functions with different function signatures will generate a corresponding wrapper function in FunctionBridge.h. Of course, we also support calling through reflection, which has slightly lower performance.
  • Generate for xIl2cpp mode will traverse all Assemblies and generate wrappers for all functions. In addition, generate/FunctionBridge.h(Configure) is also provided, which will only generate wrappers for the configured classes in the generation list, and the rest will be called using reflection mechanism.
  • Generate/FunctionBridge.h also generates a bridge for calling from C# to JS, so UsingFunc and UsingAction are no longer needed.
  • The PUERTS_CPP_OUTPUT_TO_NATIVE_SRC_UPM in the installation steps is to allow FunctionBridge.h to be generated directly to the native_src_il2cpp directory and Puerts_il2cpp.cpp to be generated to the Plugins directory. If you are not using the upm method to install puerts, you can omit this def and copy these files to the correct location yourself.

FAQ​

  1. The header file hash_map cannot be found when building iOS. When Unity is built, some header files will not be automatically packaged into the xcode project. You can find the missing content in your Unity.app/Contents/il2cpp/external/ and copy it to iosbuild directory/Libraries/external/.
  2. ReentrantLock is ambigious in iOS build Common found in Unity2022+. See https://github.com/Tencent/puerts/issues/1428