Method InstantiateAsync

InstantiateAsync(IResourceLocation, Transform, bool, bool)

Instantiate a single object.

Declaration

public static AsyncOperationHandle<GameObject> InstantiateAsync(IResourceLocation location, Transform parent = null, bool instantiateInWorldSpace = false, bool trackHandle = true)

Parameters

Type	Name	Description
IResourceLocation	location	The location of the Object to instantiate.
Transform	parent	Parent transform for instantiated object.
bool	instantiateInWorldSpace	Option to retain world space when instantiated with a parent.
bool	trackHandle	If true, Addressables will track this request to allow it to be released via the result object.

Returns

Type	Description
AsyncOperationHandle<GameObject>	AsyncOperationHandle that is used to check when the operation has completed. The result of the operation is a GameObject.

Remarks

Loads a Prefab and instantiates a copy of the prefab into the active scene or parent GameObject. The Prefab and any resources associated with it are loaded asynchronously, whereas the instantiation is executed synchronously. In the situation where the Prefab and resources are already loaded, the entire operation is completed synchronously.

Most versions of the function shares the same parameters(position, rotation, etc.) as Object.Instantiate. You can create an InstantiationParameters struct to store these parameters, pass it into the function instead.

Examples

The example below instantiates a GameObject using by a key, specifically an AssetReference. By default trackHandle is set to true. Since the instance is tracked, a reference from the instance to the handle is stored and released via ReleaseInstance(GameObject). Alternatively a reference to the operation handle can be stored and released via Release(AsyncOperationHandle), similar to the second example below.

public AssetReferenceGameObject assetRefTracked; // Identify the asset
public Transform parentTransformTracked; // Identify the transform of the parent GameObject
GameObject instanceTracked;

void UsingInstantiateAsyncSampleKeyTracked()
{
    var instParams = new InstantiationParameters(parentTransformTracked, false);
    Addressables.InstantiateAsync(assetRefTracked, instParams).Completed += OnInstantiateCompleteObjectTracked;
}

void OnInstantiateCompleteObjectTracked(AsyncOperationHandle<GameObject> handle)
{
    if (handle.Status == AsyncOperationStatus.Succeeded)
    {
        instanceTracked = handle.Result;
        Debug.Log($"Successfully instantiated GameObject with name '{instanceTracked.name}'.");
    }
}

void ReleaseTrackedResources()
{
    Addressables.ReleaseInstance(instanceTracked);
}

// When ready to release the asset, call ReleaseTrackedResources().
// For example during OnDestroy().
//void OnDestroy()
//{
//    ReleaseTrackedResources();
//}

The example below shows how to release a GameObject when trackHandle is set to false. The instance is not tracked and cannot be used to release the object, instead a reference to the operation handle is stored and released via Release(AsyncOperationHandle).

public AssetReferenceGameObject assetRefUntracked; // Identify the asset
public Transform parentTransformUntracked; // Identify the transform component of the parent GameObject
AsyncOperationHandle<GameObject> handleUntracked;

void UsingInstantiateAsyncSampleKeyUntracked()
{
    var instParams = new InstantiationParameters(parentTransformUntracked, false);
    handleUntracked = Addressables.InstantiateAsync(assetRefUntracked, instParams, false);
    handleUntracked.Completed += OnInstantiateCompleteObjectUntracked;
}

void OnInstantiateCompleteObjectUntracked(AsyncOperationHandle<GameObject> handle)
{
    if (handle.Status == AsyncOperationStatus.Succeeded)
    {
        Debug.Log($"Successfully instantiated GameObject with name '{handle.Result.name}'.");
    }
}

void ReleaseUntrackedResources()
{
    Addressables.Release(handleUntracked);
}

// When ready to release the asset, call ReleaseUntrackedResources().
// For example during OnDestroy().
//void OnDestroy()
//{
//    ReleaseUntrackedResources();
//}

The example below instantiates a GameObject using an IResourceLocation.

public AssetReferenceGameObject assetRefLocation; // Identify the asset
public Transform parentTransformLocation; // Identify the transform of the parent GameObject
AsyncOperationHandle<IList<IResourceLocation>> locHandle;
GameObject instanceLocation;

void UsingInstantiateAsyncSampleLocation()
{
    locHandle = Addressables.LoadResourceLocationsAsync(assetRefLocation, typeof(GameObject));
    locHandle.Completed += OnLoadComplete;
}

void OnLoadComplete(AsyncOperationHandle<IList<IResourceLocation>> handle)
{
    if (handle.Status == AsyncOperationStatus.Succeeded)
    {
        Debug.Log($"Successfully loaded resource locations");
        foreach (IResourceLocation location in handle.Result)
        {
            string locationKey = location.InternalId;
            var instParams = new InstantiationParameters(parentTransformLocation, false);
            Addressables.InstantiateAsync(location, instParams).Completed += OnInstantiateCompleteLocation;
        }
    }
}

void OnInstantiateCompleteLocation(AsyncOperationHandle<GameObject> handle)
{
    if (handle.Status == AsyncOperationStatus.Succeeded)
    {
        instanceLocation = handle.Result;
        Debug.Log($"Successfully instantiated GameObject with name '{instanceLocation.name}'.");
    }
}

void ReleaseResourcesLocation()
{
    Addressables.Release(locHandle);
    Addressables.ReleaseInstance(instanceLocation);
}

// When ready to release the asset, call ReleaseTrackedResources().
// For example during OnDestroy().
//void OnDestroy()
//{
//    ReleaseResourcesLocation();
//}

InstantiateAsync(IResourceLocation, Vector3, Quaternion, Transform, bool)

Instantiate a single object.

Declaration

public static AsyncOperationHandle<GameObject> InstantiateAsync(IResourceLocation location, Vector3 position, Quaternion rotation, Transform parent = null, bool trackHandle = true)

Parameters

Type	Name	Description
IResourceLocation	location	The location of the Object to instantiate.
Vector3	position	The position of the instantiated object.
Quaternion	rotation	The rotation of the instantiated object.
Transform	parent	Parent transform for instantiated object.
bool	trackHandle	If true, Addressables will track this request to allow it to be released via the result object.

Returns

Type	Description
AsyncOperationHandle<GameObject>	AsyncOperationHandle that is used to check when the operation has completed. The result of the operation is a GameObject.

InstantiateAsync(object, Transform, bool, bool)

Instantiate a single object.

Declaration

public static AsyncOperationHandle<GameObject> InstantiateAsync(object key, Transform parent = null, bool instantiateInWorldSpace = false, bool trackHandle = true)

Parameters

Type	Name	Description
object	key	The key of the location of the Object to instantiate.
Transform	parent	Parent transform for instantiated object.
bool	instantiateInWorldSpace	Option to retain world space when instantiated with a parent.
bool	trackHandle	If true, Addressables will track this request to allow it to be released via the result object.

Returns

Type	Description
AsyncOperationHandle<GameObject>	AsyncOperationHandle that is used to check when the operation has completed. The result of the operation is a GameObject.

InstantiateAsync(object, Vector3, Quaternion, Transform, bool)

Instantiate a single object.

Declaration

public static AsyncOperationHandle<GameObject> InstantiateAsync(object key, Vector3 position, Quaternion rotation, Transform parent = null, bool trackHandle = true)

Parameters

Type	Name	Description
object	key	The key of the location of the Object to instantiate.
Vector3	position	The position of the instantiated object.
Quaternion	rotation	The rotation of the instantiated object.
Transform	parent	Parent transform for instantiated object.
bool	trackHandle	If true, Addressables will track this request to allow it to be released via the result object.

Returns

Type	Description
AsyncOperationHandle<GameObject>	AsyncOperationHandle that is used to check when the operation has completed. The result of the operation is a GameObject.

InstantiateAsync(object, InstantiationParameters, bool)

Instantiate a single object.

Declaration

public static AsyncOperationHandle<GameObject> InstantiateAsync(object key, InstantiationParameters instantiateParameters, bool trackHandle = true)

Parameters

Type	Name	Description
object	key	The key of the location of the Object to instantiate.
InstantiationParameters	instantiateParameters	Parameters for instantiation.
bool	trackHandle	If true, Addressables will track this request to allow it to be released via the result object.

Returns

Type	Description
AsyncOperationHandle<GameObject>	AsyncOperationHandle that is used to check when the operation has completed. The result of the operation is a GameObject.

InstantiateAsync(IResourceLocation, InstantiationParameters, bool)

Instantiate a single object.

Declaration

public static AsyncOperationHandle<GameObject> InstantiateAsync(IResourceLocation location, InstantiationParameters instantiateParameters, bool trackHandle = true)

Parameters

Type	Name	Description
IResourceLocation	location	The location of the Object to instantiate.
InstantiationParameters	instantiateParameters	Parameters for instantiation.
bool	trackHandle	If true, Addressables will track this request to allow it to be released via the result object.

Returns

Type	Description
AsyncOperationHandle<GameObject>	AsyncOperationHandle that is used to check when the operation has completed. The result of the operation is a GameObject.