Instance

An instance is a reproduction of a template. In the real world, if you have plans to build a house, you can build many houses based on the same plans. Each house would be an "instance" of the plans.

In programming, similarly, you can create as many objects as you want from a class or a scene. We say that each object is an instance of the class or scene it was created from.

In Godot, there are two mechanisms to create instances:

1. We use the .new() function for class instances.
2. We use the .instantiate() function for scene instances.

Creating class instances in GDScript

You can create class instances, such as nodes or resources classes, with the .new() method.

For example, to create a Node2DNode2D node instance in code, you would write:

var my_node := Node2D.new()

To create a new ImageImage resource instance, you would write:

var my_image := Image.new()

Godot creates a fresh reproduction of the class with default properties in both cases.

Creating scene instances in GDScript

To instantiate a scene from a loaded PackedScenePackedScene resource, we use the packed scene's .instantiate() method.

For example, to create a new instance of a particular scene, you would write:

var packed_scene_resource := preload("my_scene.tscn")
var scene_instance = packed_scene_resource.instantiate()

Or, in a single line:

var scene_instance = preload("my_scene.tscn").instantiate()

Why don't we use `.new()` for scenes?

The .new() method creates a new class instance. A loaded PackedScenePackedScene resource is not a class. It's an object and an instance of the PackedScenePackedScene class. So, when you load a scene in code, the loaded resource does not have a .new() method.

The PackedScenePackedScene class itself has a .new() method, but calling it creates an empty scene template, not an instance of a scene file. The following code would create an empty scene template:

var my_scene := PackedScene.new()