Unity provides a common scripting API and experience across all platforms it supports. However, some platforms have inherent restrictions. To help you understand these restrictions, the following table describes which restrictions apply to each platform and scripting backendA framework that powers scripting in Unity. Unity supports three different scripting backends depending on target platform: Mono, .NET and IL2CPP. Universal Windows Platform, however, supports only two: .NET and IL2CPP. More info
See in Glossary:
Platform (scripting backend) | Ahead-of-time compile | Supports threads |
---|---|---|
Android (IL2CPP) | Yes | Yes |
Android (Mono) | No | Yes |
iOS (IL2CPP) | Yes | Yes |
Standalone (IL2CPP) | Yes | Yes |
Standalone (Mono) | No | Yes |
Universal Windows Platform (IL2CPP) | Yes | Yes |
Web (IL2CPP) | Yes | No |
Some platforms don’t allow runtime code generation. Any managed code which depends upon just-in-time (JIT) compilation on the target device will fail. Instead, you must compile all the managed code ahead-of-time (AOT). Often, this distinction doesn’t matter, but in a few specific cases, AOT platforms require additional consideration.
Unity supports reflection on AOT platforms. However, if this compiler can’t infer that the code is used via reflection the code might not exist at runtime. For more information, refer to Managed Code Stripping.
An AOT platform cannot implement any of the methods in the System.Reflection.Emit
namespace.
AOT platforms might encounter issues with serialization and deserialization because of the use of reflection. If a type or method is only used via reflection as part of serialization or deserialization, the AOT compiler cannot detect that it needs to generate the code needs for the type or method.
For generic types and methods the compiler must determine which generic instances are used because different generic instances might require different code. For example the code for List<int>
is different than it is for List<double>
. However IL2CPP will share code for usages for reference types, so the same code will be used for List<object>
and List<string>
.
It is possible to reference generic types and methods that 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 did not find a compile time in the following cases:
Activator.CreateInstance(typeof(SomeGenericType<>).MakeGenericType(someType));
typeof(SomeGenericType<>).MakeGenericType(someType)).GetMethod(“AMethod”).Invoke(null, null);
typeof(SomeType).GetMethod(“GenericMethod”).MakeGenericMethod(someType).Invoke(null, null);
Struct<Struct<Struct<...<Struct<int>>>>
.To support those cases IL2CPP generates generic code that will work with any type parameter. However this code is slower because it can make no assumptions on the size of the type or if it is a reference or value type. If you need to ensure that faster generic methods are generated, do the following:
where: class
constraint. Then IL2CPP will generate the fallback method using reference type sharing which causes no performance degradation.where: struct
constraint. This enables some optimizations, but the code will still be slower because the value types can be different sizes.UsedOnlyForAOTCodeGeneration
and add references to the generic types and methods you wish IL2CPP to generate. This method does not need (and probably shouldn’t) be called. The example below will ensure that a specialization for GenericType<MyStruct>
will be generated.public void UsedOnlyForAOTCodeGeneration()
{
// Ensure that IL2CPP will create code for MyGenericStruct
// using MyStruct as an argument.
new GenericType<MyStruct>();
// Ensure that IL2CPP will create code for SomeType.GenericMethod
// using MyStruct as an argument.
new SomeType().GenericMethod<MyStruct>();
public void OnMessage<T>(T value)
{
Debug.LogFormat("Message value: {0}", value);
}
// Include an exception so we can be sure to know if this
// method is ever called.
throw new InvalidOperationException(
"This method is used for AOT code generation only. " +
"Do not call it at runtime.");
}
Note that when the “Faster (smaller) builds” setting is enabled only the single fully sharable version of generic code is compiled. This reduces the number of methods generated, reducing compile time and build size, but comes at the expense of runtime performance.
Managed methods that need to be marshaled to a C function pointer so that they can be called from native code have a few restrictions on AOT platforms:
[MonoPInvokeCallback]
attribute[MonoPInvokeCallback(Type)]
overload might need to be used to specify the generic specializations that need to be supported. If so, the type must be a generic instance with the correct number of generic arguments. It’s possible to have multiple [MonoPInvokeCallback]
attributes on a method as below:// Generates reverse P/Invoke wrappers for NameOf<long> and NameOf<int>
// Note that the types are only used to indicate the generic arguments.
[MonoPInvokeCallback(typeof(Action<long>))]
[MonoPInvokeCallback(typeof(Action<int>))]
private static string NameOfT<T>(T item)
{
return typeof(T).Name;
}
Some platforms do not support the use of threads, so any managed code that uses the System.Threading
namespace fails at runtime. Also, some parts of the .NET class libraries implicitly depend upon threads. An often-used example is the System.Timers.Timer
class, which depends on support for threads.
IL2CPP supports exception filters, however the execution order filter statements and catch blocks is different because IL2CPP uses C++ exceptions to implement managed exceptions. This will not be noticeable unless a filter blocks writes to a field.
IL2CPP does not support reflection of the MarshalAs
and FieldOffset
attributes at runtime. It does support these attributes at compile time. You should use these for proper platform invoke marshaling.
IL2CPP does not support the C# dynamic
keyword. This keyword requires JIT compilation, which is not possible with IL2CPP.
IL2CPP doesn’t support the Marshal.Prelink
or Marshal.PrelinkAll
API methods.
IL2CPP doesn’t support the System.Diagnostics.Process
API methods. For cases where this is required on desktop platforms, use the Mono scripting backend.
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thank you for helping to make the Unity documentation better!
Your feedback has been submitted as a ticket for our documentation team to review.
We are not able to reply to every ticket submitted.
When you visit any website, it may store or retrieve information on your browser, mostly in the form of cookies. This information might be about you, your preferences or your device and is mostly used to make the site work as you expect it to. The information does not usually directly identify you, but it can give you a more personalized web experience. Because we respect your right to privacy, you can choose not to allow some types of cookies. Click on the different category headings to find out more and change our default settings. However, blocking some types of cookies may impact your experience of the site and the services we are able to offer.
More information
These cookies enable the website to provide enhanced functionality and personalisation. They may be set by us or by third party providers whose services we have added to our pages. If you do not allow these cookies then some or all of these services may not function properly.
These cookies allow us to count visits and traffic sources so we can measure and improve the performance of our site. They help us to know which pages are the most and least popular and see how visitors move around the site. All information these cookies collect is aggregated and therefore anonymous. If you do not allow these cookies we will not know when you have visited our site, and will not be able to monitor its performance.
These cookies may be set through our site by our advertising partners. They may be used by those companies to build a profile of your interests and show you relevant adverts on other sites. They do not store directly personal information, but are based on uniquely identifying your browser and internet device. If you do not allow these cookies, you will experience less targeted advertising. Some 3rd party video providers do not allow video views without targeting cookies. If you are experiencing difficulty viewing a video, you will need to set your cookie preferences for targeting to yes if you wish to view videos from these providers. Unity does not control this.
These cookies are necessary for the website to function and cannot be switched off in our systems. They are usually only set in response to actions made by you which amount to a request for services, such as setting your privacy preferences, logging in or filling in forms. You can set your browser to block or alert you about these cookies, but some parts of the site will not then work. These cookies do not store any personally identifiable information.