Instantiate
Clones the object original and sets the position and rotation of the clone.
Read time 9 minutesLast updated 4 days ago
Definition
- Type: Method
- Namespace: UnityEngine
- Assembly: UnityEngine.CoreModule
Instantiate(Object, Vector3, Quaternion)
Clones the object and sets the position and rotation of the clone.
originalpublic static Object Instantiate(Object original, Vector3 position, Quaternion rotation)
Parameters
An existing object that you want to make a copy of.
The position for the new object, in world space.
The orientation of the new object.
Returns
Type | Description |
|---|---|
| Object | The instantiated clone. |
Remarks
Unity uses the and that you specify as the clone's position and rotation in world space. The new object has no parent.
positionrotationYou 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 velocitypublic 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 otherusing 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); } }}
Instantiate(Object, Vector3, Quaternion, Transform)
Clones the object , sets the position and rotation of the clone, and sets as the parent of the clone.
originalparentpublic static Object Instantiate(Object original, Vector3 position, Quaternion rotation, Transform parent)
Parameters
An existing object that you want to make a copy of.
The position for the new object, in world space.
The orientation of the new object.
Returns
Type | Description |
|---|---|
| Object | The instantiated clone. |
Remarks
Unity uses the and that you specify as the clone's position and rotation in world space, and sets as the parent of the clone.
positionrotationparentInstantiate(Object)
Clones the object and returns the clone.
originalpublic static Object Instantiate(Object original)
Parameters
An existing object that you want to make a copy of.
Returns
Type | Description |
|---|---|
| Object | The instantiated clone. |
Remarks
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 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.
originalThe clone keeps the active state of the original, so if is inactive, the clone is also inactive. For the clone and each object in its hierarchy, Unity calls the and methods on a MonoBehaviour or Component only if it's active in the hierarchy when you call this method.
originalAwakeOnEnableNote: 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 .
InsufficientExecutionStackExceptionThis 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:
Instantiate(Object, Scene)
Clones the object and adds the clone to the specified scene.
originalpublic static Object Instantiate(Object original, Scene scene)
Parameters
Returns
Type | Description |
|---|---|
| Object | The instantiated clone. |
Remarks
This overload adds the clone to a specific loaded scene instead of the active scene.
Instantiate<T>(T, InstantiateParameters)
Clones the object of type T using the settings in , and returns the clone.
parameterspublic static T Instantiate<T>(T original, InstantiateParameters parameters) where T : Object
Parameters
An InstantiateParameters struct that specifies options for the new object, such as its parent, the scene to add it to, and whether to use world space.
Returns
Type | Description |
|---|---|
| T | The instantiated cloned object of type T. |
Instantiate<T>(T, Vector3, Quaternion, InstantiateParameters)
Clones the object of type T, sets the position and rotation of the clone, and applies the settings in .
parameterspublic static T Instantiate<T>(T original, Vector3 position, Quaternion rotation, InstantiateParameters parameters) where T : Object
Parameters
The position for the new object, in world space.
The orientation of the new object.
An InstantiateParameters struct that specifies options for the new object, such as its parent, the scene to add it to, and whether to use world space.
Returns
Type | Description |
|---|---|
| T | The instantiated cloned object of type T. |
Instantiate(Object, Transform)
Clones the object and sets as the parent of the clone.
originalparentpublic static Object Instantiate(Object original, Transform parent)
Parameters
Returns
Type | Description |
|---|---|
| Object | The instantiated clone. |
Remarks
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 .
parentTo keep the existing object's world position and rotation instead, use Object.Instantiate(Object, Transform, bool) and set to true.
instantiateInWorldSpaceInstantiate(Object, Transform, bool)
Clones the object , sets as the parent of the clone, and sets whether the clone keeps its local or world position.
originalparentpublic static Object Instantiate(Object original, Transform parent, bool instantiateInWorldSpace)
Parameters
Returns
Type | Description |
|---|---|
| Object | The instantiated clone. |
Remarks
If is false, Unity uses the existing object's position and rotation as the clone's local position and rotation, relative to . If is true, Unity keeps the existing object's world position and rotation.
instantiateInWorldSpaceparentinstantiateInWorldSpaceThe 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.
Examples
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); }}
Instantiate<T>(T)
Clones the object of type T and returns the clone.
public static T Instantiate<T>(T original) where T : Object
Parameters
Returns
Type | Description |
|---|---|
| T | The instantiated cloned object of type T. |
Remarks
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.
Examples
using UnityEngine;public class Missile : MonoBehaviour{ // ...other code...}public class InstantiateGenericsExample : MonoBehaviour{ public Missile missile; void Start() { Missile missileCopy = Instantiate<Missile>(missile); }}
Instantiate<T>(T, Vector3, Quaternion)
Clones the object of type T and sets the position and rotation of the clone.
public static T Instantiate<T>(T original, Vector3 position, Quaternion rotation) where T : Object
Parameters
The position for the new object, in world space.
The orientation of the new object.
Returns
Type | Description |
|---|---|
| T | The instantiated cloned object of type T. |
Instantiate<T>(T, Vector3, Quaternion, Transform)
Clones the object of type T, sets the position and rotation of the clone, and sets as the parent of the clone.
parentpublic static T Instantiate<T>(T original, Vector3 position, Quaternion rotation, Transform parent) where T : Object
Parameters
The position for the new object, in world space.
The orientation of the new object.
Returns
Type | Description |
|---|---|
| T | The instantiated cloned object of type T. |
Instantiate<T>(T, Transform)
Clones the object of type T and sets as the parent of the clone.
parentpublic static T Instantiate<T>(T original, Transform parent) where T : Object
Parameters
Returns
Type | Description |
|---|---|
| T | The instantiated cloned object of type T. |
Instantiate<T>(T, Transform, bool)
Clones the object of type T, sets as the parent of the clone, and sets whether the clone keeps its local or world position.
parentpublic static T Instantiate<T>(T original, Transform parent, bool worldPositionStays) where T : Object
Parameters
Returns
Type | Description |
|---|---|
| T | The instantiated cloned object of type T. |