Object.Instantiate

Parameters

Returns

Object The instantiated clone.

Description

Clones the object original and returns the clone.

This method makes a copy of an object, similar to the Duplicate command in the Editor.

When you clone a GameObject or Component, Unity also clones all of its child objects and components, and sets their properties to match the original. If you clone a Component, Unity also clones the GameObject that the component is attached to.

This overload doesn't set a position, rotation, or parent for the clone. By default, the new object has no parent, even if original has one. To set a position, rotation, or parent, use one of the other overloads, or an overload that takes an InstantiateParameters struct to pass any combination of these values.

The clone keeps the active state of the original, so if original is inactive, the clone is also inactive. For the clone and each object in its hierarchy, Unity calls the Awake and OnEnable methods on a MonoBehaviour or Component only if it's active in the hierarchy when you call this method.

Note: When this method clones a child object, it also clones that child's own children. To prevent a stack overflow, Unity limits this nested cloning. If the cloning exceeds more than half of the stack size, Unity throws an InsufficientExecutionStackException.

This method doesn't create a prefab connection to the new object. To create an object with a prefab connection, use PrefabUtility.InstantiatePrefab instead.

Additional resources:

Instantiating prefabs at run time
PrefabUtility.InstantiatePrefab.

Parameters

Returns

Object The instantiated clone.

Description

Clones the object original and adds the clone to the specified scene.

This overload adds the clone to a specific loaded scene instead of the active scene.

Parameters

Returns

Object The instantiated clone.

Description

Clones the object original and sets parent as the parent of the clone.

This overload sets a parent for the clone but doesn't set a position or rotation. Unity uses the existing object's position and rotation as the clone's local position and rotation, relative to parent.

To keep the existing object's world position and rotation instead, use Object.Instantiate(Object,Transform,bool) and set instantiateInWorldSpace to true.

Parameters

Returns

Object The instantiated clone.

Description

Clones the object original, sets parent as the parent of the clone, and sets whether the clone keeps its local or world position.

If instantiateInWorldSpace is false, Unity uses the existing object's position and rotation as the clone's local position and rotation, relative to parent. If instantiateInWorldSpace is true, Unity keeps the existing object's world position and rotation.

The following example instantiates a prefab as a child of another GameObject, first keeping the prefab's local position relative to the parent, then keeping its original world position.

using UnityEngine;

// Instantiate a Prefab as a child of another object.

public class Example : MonoBehaviour
{
    // Assign a Prefab in the Inspector.
    public GameObject prefab;

    // Assign the Transform to use as the parent in the Inspector.
    public Transform parent;

    void Start()
    {
        // Instantiate the Prefab as a child of parent.
        // The clone keeps its local position and rotation relative to parent.
        Instantiate(prefab, parent);

        // Pass true for instantiateInWorldSpace to keep the Prefab's
        // original world position and rotation instead.
        Instantiate(prefab, parent, true);
    }
}

Parameters

Returns

Object The instantiated clone.

Description

Clones the object original and sets the position and rotation of the clone.

Unity uses the position and rotation that you specify as the clone's position and rotation in world space. The new object has no parent.

You can use this method to create new objects at runtime, such as projectiles or particle systems for explosion effects.

using UnityEngine;

// Instantiate a rigidbody then set the velocity

public class Example : MonoBehaviour
{
    // Assign a Rigidbody component in the inspector to instantiate

    public Rigidbody projectile;

    void Update()
    {
        // Ctrl was pressed, launch a projectile
        if (Input.GetButtonDown("Fire1"))
        {
            // Instantiate the projectile at the position and rotation of this transform
            Rigidbody clone;
            clone = Instantiate(projectile, transform.position, transform.rotation);

            // Give the cloned object an initial velocity along the current
            // object's Z axis
            clone.velocity = transform.TransformDirection(Vector3.forward * 10);
        }
    }
}

You can also use this method to clone script instances directly. Unity clones the entire GameObject hierarchy and returns the cloned script instance.

using UnityEngine;
using System.Collections;

public class Missile : MonoBehaviour
{
    public int timeoutDestructor;

    // ...other code...
}


public class ExampleClass : MonoBehaviour
{
    // Instantiate a Prefab with an attached Missile script
    public Missile projectile;

    void Update()
    {
        // Ctrl was pressed, launch a projectile
        if (Input.GetButtonDown("Fire1"))
        {
            // Instantiate the projectile at the position and rotation of this transform
            Missile clone = Instantiate(projectile, transform.position, transform.rotation);

            // Set the missiles timeout destructor to 5
            clone.timeoutDestructor = 5;
        }
    }
}

You can also instantiate multiple clones at different positions.

// Instantiates 10 copies of Prefab each 2 units apart from each other

using UnityEngine;

public class Example : MonoBehaviour
{
    public GameObject prefab;
    void Start()
    {
        for (var i = 0; i < 10; i++)
        {
            Instantiate(prefab, new Vector3(i * 2.0f, 0, 0), Quaternion.identity);
        }
    }
}

Parameters

Returns

Object The instantiated clone.

Description

Clones the object original, sets the position and rotation of the clone, and sets parent as the parent of the clone.

Unity uses the position and rotation that you specify as the clone's position and rotation in world space, and sets parent as the parent of the clone.

Parameters

Returns

T The instantiated cloned object of type T.

Description

Clones the object of type T and returns the clone.

You can use generic types to instantiate objects so you don't have to cast the result to a specific type. For more information on generics in C#, refer to Microsoft's Generic methods documentation.

using UnityEngine;

public class Missile : MonoBehaviour
{
    // ...other code...
}

public class InstantiateGenericsExample : MonoBehaviour
{
    public Missile missile;

    void Start()
    {
        Missile missileCopy = Instantiate<Missile>(missile);
    }
}

Parameters

Returns

T The instantiated cloned object of type T.

Description

Clones the object of type T using the settings in parameters, and returns the clone.

Parameters

Returns

T The instantiated cloned object of type T.

Description

Clones the object of type T and sets parent as the parent of the clone.

Parameters

Returns

T The instantiated cloned object of type T.

Description

Clones the object of type T, sets parent as the parent of the clone, and sets whether the clone keeps its local or world position.

Parameters

Returns

T The instantiated cloned object of type T.

Description

Clones the object of type T and sets the position and rotation of the clone.

Parameters

Returns

T The instantiated cloned object of type T.

Description

Clones the object of type T, sets the position and rotation of the clone, and applies the settings in parameters.

Parameters

Returns

T The instantiated cloned object of type T.

Description

Clones the object of type T, sets the position and rotation of the clone, and sets parent as the parent of the clone.