You can use the [Il2CppSetOption] C# attribute and its Option parameter to control which safety checks the IL2CPPA Unity-developed scripting back-end which you can use as an alternative to Mono when building projects for some platforms. More info
See in Glossary compiler includes in the C++ code it generates.
The [Il2CppSetOption] attribute is not part of the standard Unity Editor and Engine public APIs but its source is shipped separately as part of your Unity installation. To use the [Il2CppSetOption] attribute:
Data\il2cpp directory on Windows, or the Contents/Frameworks/il2cpp directory on macOS.Il2CppSetOptionAttribute.cs source file.Assets folder.The supported options for the attribute are as follows:
| Property | Description | Default |
|---|---|---|
| Null checks | It’s recommended to keep this option enabled. When disabled, IL2CPP generates C++ without null checks and won’t throw managed NullReferenceException exceptions. This can improve runtime performance, but attempts to access null values won’t be prevented, which can lead to unintended behavior including crashes. |
Enabled |
| Array bounds checks | It’s recommended to keep this option enabled. When disabled, IL2CPP generates C++ without array bounds checks and won’t throw managed IndexOutOfRangeException exceptions. This might improve runtime performance but allows code to access an array with invalid indices, which can lead to incorrect behavior, including reading from or writing to arbitrary memory locations. In most cases, these memory accesses occur without any immediate side effects, and can corrupt the state of the application with no obvious warning signs, making the errors very hard to debug. |
Enabled |
| Divide by zero checks | Keep this option disabled unless you need to run divide by zero checks. When enabled, IL2CPP generates C++ that contains divide by zero checks for integer division and throws managed DivideByZeroException exceptions as necessary. If this option is disabled, IL2CPP doesn’t emit the divide by zero checks on integer division into the generated C++ code. These checks have an impact on performance at runtime. |
Disabled |
The following example shows how to use the [Il2CppSetOption] attribute:
[Il2CppSetOption(Option.NullChecks, false)]
public static string MethodWithNullChecksDisabled()
{
var tmp = new object();
return tmp.ToString();
}
You can apply [Il2CppSetOption] to assemblies, types, methods, and properties. Unity uses the attribute from the most local scope.
[Il2CppSetOption(Option.NullChecks, false)]
public class TypeWithNullChecksDisabled
{
public static string AnyMethod()
{
// Unity doesn’t perform null checks in this method.
var tmp = new object();
return tmp.ToString();
}
[Il2CppSetOption(Option.NullChecks, true)]
public static string MethodWithNullChecksEnabled()
{
// Unity performs null checks in this method.
var tmp = new object();
return tmp.ToString();
}
}
public class SomeType
{
[Il2CppSetOption(Option.NullChecks, false)]
public string PropertyWithNullChecksDisabled
{
get
{
// Unity doesn't perform null checks here.
var tmp = new object();
return tmp.ToString();
}
set
{
// Unity doesn't perform null checks here.
value.ToString();
}
}
public string PropertyWithNullChecksDisabledOnGetterOnly
{
[Il2CppSetOption(Option.NullChecks, false)]
get
{
// Unity doesn’t perform null checks here.
var tmp = new object();
return tmp.ToString();
}
set
{
// Unity performs null checks here.
value.ToString();
}
}
}