This document provides an API reference for the Swift project type in Unity.
You can use native plug-insA set of code created outside of Unity that creates functionality in Unity. There are two kinds of plug-ins you can use in Unity: Managed plug-ins (managed .NET assemblies created with tools like Visual Studio) and Native plug-ins (platform-specific native code libraries). More info
See in Glossary to pause and resume the execution of the Unity Player. When you call the pause() method, Unity pauses execution after the current player loop finishes. Unity also invokes MonoBehaviour.OnApplicationPause with a true parameter.
When you call resume(), Unity calls OnApplicationPause with a false parameter, and the player loop continues as normal. The isPaused() method returns true after you call pause(), and false after you call resume().
Public API: UnityPlayer class
static var shared: UnityPlayerfunc pause()func resume()func isPaused() -> BoolUsage examples:
Use the following code format for Swift plug-ins:
UnityPlayer.shared.isPaused()
UnityPlayer.shared.pause()
UnityPlayer.shared.resume()
Use the following code format for Objective-C plug-ins:
[[UnityPlayer shared] isPaused]
[[UnityPlayer shared] pause]
[[UnityPlayer shared] resume]
Use the following Lifecycle APIs to allow a plug-in to react to application lifecycle events.
On iOS, applications typically handle lifecycle events in UIApplicationDelegate or UISceneDelegate. However, an application can only have one delegate, which is a challenge because multiple plug-ins, including Unity’s internal UnityPlayer, often need to handle these events. To solve this, Unity provides a mechanism to share these events with plug-ins through notifications.
To receive these events, subscribe to the notification center using NSNotificationCenter in Objective-C or NotificationCenter in Swift. To avoid duplicating existing system notifications, Unity provides only the notifications that are otherwise unavailable.
The following notifications are available:
| Notification | Type | Description |
|---|---|---|
class UnityNotifications |
object | A class object to store the notification references. |
UnityNotifications.applicationWillFinishLaunching |
var |
UnityPlayer posts this notification after it handles application(_:willFinishLaunchingWithOptions:). |
UnityNotifications.applicationDidFailToRegisterForRemoteNotifications |
var |
UnityPlayer posts this notification after it handles application(_:didFailToRegisterForRemoteNotificationsWithError:). The notification’s userInfo dictionary contains the registration error under the remoteNotificationsErrorKey key. |
UnityNotifications.remoteNotificationsErrorKey |
var | A string value for the dictionary key for the error value. |
UnityNotifications.applicationDidReceiveRemoteNotification |
var |
UnityPlayer posts this notification after it handles application(_:didReceiveRemoteNotification:fetchCompletionHandler:). The notification’s userInfo dictionary contains the remote notification payload. |
UnityNotifications.applicationDidRegisterForRemoteNotifications |
var |
UnityPlayer posts this notification after it handles application(_:didRegisterForRemoteNotificationsWithDeviceToken:). The notification’s userInfo dictionary contains the device token under the remoteNotificationsDeviceTokenKey key. |
UnityNotifications.remoteNotificationsDeviceTokenKey |
var | A string value for the dictionary key that contains the device token. |
UnityNotifications.applicationHandleEventsForBackgroundURLSession |
var |
UnityPlayer posts this notification after it handles application(_:handleEventsForBackgroundURLSession:completionHandler:). The notification’s userInfo dictionary contains the URL session identifier under backgroundURLSessionIdentifierKey and the completion handler block under backgroundURLSessionCompletionHandlerKey.
|
UnityNotifications.backgroundURLSessionIdentifierKey |
var | A string value for the dictionary key that contains the URL session identifier. |
UnityNotifications.backgroundURLSessionCompletionHandlerKey |
var | A string value for the dictionary key that contains the completion handler block. |
UnityNotifications.sceneOpenURLContexts |
var |
UnityPlayer posts this notification after it handles scene(_:openURLContexts:). The notification’s userInfo dictionary contains the sceneA Scene contains the environments and menus of your game. Think of each unique Scene file as a unique level. In each Scene, you place your environments, obstacles, and decorations, essentially designing and building your game in pieces. More infoSee in Glossary instance under sceneKey and the URL contexts set under openURLContextsKey. |
UnityNotifications.sceneKey |
var | A string value for the dictionary key that contains the scene instance. |
UnityNotifications.openURLContextsKey |
var | A string value for the dictionary key that contains the set of URL contexts. |
UnityNotifications.unityDidInitializeRuntime |
var |
UnityPlayer posts this notification when the Unity runtime initializes, before any game logic or rendering starts. This provides an opportunity for low-level plug-ins to initialize before the first scene loads. At this point, the Unity runtime is ready but no game code is running. |
UnityNotifications.unityDidUnload |
var |
UnityPlayer posts this notification when Application.Unload is called from C# scripting. |
UnityNotifications.unityDidQuit |
var |
UnityPlayer posts this notification when Application.Quit is called from C# scripting. |
Unity provides proxy implementations of UIApplicationDelegate and UISceneDelegate that pass all events to the UnityPlayer for internal handling. You can replace these default implementations with your own.
To ensure Unity continues to work as expected, your custom implementation must call the respective UnityPlayer methods. The following list shows the required calls:
UnityPlayer.application(_:willFinishLaunchingWithOptions:)
UnityPlayer.application(_:didFinishLaunchingWithOptions:)
UnityPlayer.application(_:didRegisterForRemoteNotificationsWithDeviceToken:)
UnityPlayer.application(_:didReceiveRemoteNotification:fetchCompletionHandler:)
UnityPlayer.application(_:didFailToRegisterForRemoteNotificationsWithError:)
UnityPlayer.application(_:handleEventsForBackgroundURLSession:completionHandler:)
UnityPlayer.applicationWillTerminate(_:)
UnityPlayer.scene(_:willConnectTo:options:)
UnityPlayer.sceneWillResignActive(_:)
UnityPlayer.sceneDidBecomeActive(_:)
UnityPlayer.scene(_:openURLContexts:)
Note: Forcing orientation from C# scriptsA piece of code that allows you to create your own Components, trigger game events, modify Component properties over time and respond to user input in any way you like. More info
See in Glossary doesn’t work with a custom delegate implementation. If you replace the delegates, you’re responsible for your own application configuration, including any necessary orientation handling.
To send a message from your plug-in to a C# script, you can use the UnitySendMessage function. The public API for UnitySendMessage is as follows:
Symbol:
void UnitySendMessage(const char* gameObjectName, const char* method, const char* argument);
UnityPlayer function:
func sendMessage(toGameObject:method:argument:)
This function is equivalent to the GameObject.SendMessage method in the scripting API, with the following differences:
NULL or nil as the argument.The message is sent asynchronously. You can call these functions from any thread, but Unity calls the scripting method only on the main thread.
Samples:
To test this example, attach this C# script to a GameObject and rename the object ObjectName:
using UnityEngine;
public class NewMonoBehaviourScript : MonoBehaviour
{
public void MyMethod()
{
Debug.Log("MyMethod called");
}
public void MyMethodWithArg(string argument)
{
Debug.Log($"MyMethodWithArg called with '{argument}'");
}
}
Then, depending on your plug-in language (Swift, Objective C, or C++), use the following code to send a message to your GameObject and invoke its C# methods. Swift:
UnityPlayer.shared.sendMessage(toGameObject: "ObjectName", method: "MyMethod")
UnityPlayer.shared.sendMessage(toGameObject: "ObjectName", method: "MyMethodWithArg", argument: "argument")
Objective-C:
[UnityPlayer.shared sendMessageToGameObject:@"ObjectName" method:@"MyMethod" argument:nil];
[UnityPlayer.shared sendMessageToGameObject:@"ObjectName" method:@"MyMethodWithArg" argument:@"argument"];
C/C++:
UnitySendMessage("ObjectName", "MyMethod", NULL);
UnitySendMessage("ObjectName", "MyMethodWithArg", "argument");
To use UnitySendMessage from Objective-C, C++, or C, import the UnityPluginInterface.h header.
To present native content on top of the Unity view, you can get the view or view controller that Unity renders to. Use the following properties to access them:
renderingView: The same view that Unity renders to.rootViewController: The root view controller of the window where the Unity view is rendering.You can access the view and view controller that Unity renders to through the following UnityPlayer properties:
UnityPlayer:
renderingView: UIView?
rootViewController: UIViewController?
Unity supports the low-level native plug-inA platform-specific native code library that is created outside of Unity for use in Unity. Allows you can access features like OS calls and third-party code libraries that would otherwise not be available to Unity. More info
See in Glossary API on iOS. The following registration functions are exposed:
UnityRegisterAudioPlugin(UnityPluginGetAudioEffectDefinitionsFunc getAudioEffectDefinitions)UnityRegisterPlugin(UnityPluginLoadFunc loadPlugin, UnityPluginUnloadFunc unloadPlugin)The necessary headers are located in the UnityFramework/UnityPluginInterface/ directory.
These are:
IUnityEventQueue.h
IUnityGraphics.h
IUnityGraphicsMetal.h
IUnityInterface.h
IUnityLog.h
IUnityMemoryManager.h
IUnityProfiler.h
IUnityProfilerCallbacks.h
IUnityRenderingExtensions.h
You must load low-level plug-ins after the Unity runtime initializes. On iOS, subscribe to UnityNotifications.unityDidInitializeRuntime and register the plug-in when the notification is sent. This is the recommended registration point because it occurs after the Unity runtime initializes but before the first scene loads. You can also register plug-ins later from other iOS notifications or directly from your C# scripts.
Note: The UnityNotifications.unityDidInitializeRuntime registration timing is a requirement for spatial audio plug-ins setup in the first scene. If a scene in your application contains a spatial audio sourceA component which plays back an Audio Clip in the scene to an audio listener or through an audio mixer. More info
See in Glossary, you must register the plug-in before that scene loads.
You can use the PBXProject API in a C# post-process build step for both C# and Swift projects. To identify which project type is built, use the UnityEditor.PlayerSettings.XcodeProjectType property.
Note: The Xcode project name now matches the Unity project name. To avoid issues with hard-coded project names in your plug-ins, update them to use the PBXProject.GetPBXProjectPath API.
Unity defines a preprocessor macro, UNITY_XCODE_PROJECT_TYPE_SWIFT, that you can use to conditionally compile code for the Swift project type.
Usage:
#if UNITY_XCODE_PROJECT_TYPE_SWIFT
<Swift trampoline specific code>
#endif