Godot Addon - Packed Scene Instantiater

An Godot addon that helps you to quickly instantiate packed scenes in minutes.

Supported targets

Programming languages

• GDScript

Versions

• Godot: >= 4.3
• Redot: >= 4.3

Platforms

• Windows
• Linux
• macOS
• Android
• iOS
• Web

Preuse

Installation

• Download the release you want from releases and extract the addon folder to your Godot project's addons folder and cover the latter.

Since this addon is one that barely provides extra nodes, there is no plugin.cfg file, which means that you don't need to enable it in the project settings. It is enabled once you add it to your project.

Language

Currently, the addon only provides support for GDScript, as this is the language that Godot uses for its scripting and easy for beginners to understand, which will help users to give quicker feedback and DIY their own solutions based on the addon.

Due to some technical limitations, you cannot inherit a C# class from a GDScript class, vice versa. Therefore, if you are using C# for long-term development, you may consider writing manually a C# binding for the addon.

What is Packed Scene Instantiater?

Packed Scene Instantiater is an addon that provides two parts of global types: PackedSceneInstance and Instantiater*D. They works together to allow you to quickly instantiate packed scenes during your development, saving your time and effort from making wheels.

PackedSceneInstance

A PackedSceneInstance is a placeholder node used to provide encapsulation of the packed scene where it is. You can call a static method PackedSceneInstance.instantiate() to instantiate the packed scene, in which there are some parameters that worth noting:

• Array args: If you have create a script extends PackedSceneInstance, you can define a virtual method named _init_instance(), in which you can define some arguments in order to customize the behavior of the instantiation. This parameter is used for this. For example, if args is [0, "hello"], the target _init_instance() should be like this:

func _init_instance(index0: int, index1: String) -> void:
    ...

This provides the ability to encapsulate the implementation of the instantiation process, as the caller of the instantiate() doesn't need to know the details of the scene tree in which the callee PackedSceneInstance is.

• Callable callback: This is, on the opposite, a callback whose first argument must always be a Node, which is the root node of the instantiated scene. The callback will be called after the _init_instance() is called. This is used for the encapsulation of the instantiation process on the caller side, as the callee doesn't know the structure of the scene tree where the caller node is.
• Node parent_node: If this is not null, the instantiated scene will be added as a child of the parent node.
• bool deferred: If parent_node is not null, the instance will be created in the idle process (i.e. the instantiation is deferred until the idle loop runs). This is useful when the root node of the packed scene will cause flush query errors (E.g. CollisionObject*D).

When you call the instantiate() static method, the method will try to instantiate the packed scene and iterate all direct children of the root node of the instantiated scene to find the first PackedSceneInstance.If you does care the tiny performance loss caused by the iteration, it's recommended to place the PackedSceneInstance right under the root node of the packed scene (i.e. to make the PackedSceneInstance the first/top child of the root node).

Instantiater*D

Instantiater2D or Instantiater3D is a helper node that provides a convenient way to instantiate packed scenes in 2D or 3D space. In the editor, it will allow you to preview the instance you are going to create if you have provided a packed scene.
If it is necessary for you to preset a list of arguments to be passed in the PackedSceneInstance in the packed scene, using instance_init_arguments is a good idea, which allows you to preset the arguments in the editor in order. Note that the instance_init_arguments only suppports constant values, and it will be passed firstly and then the args in instantaite() will be passed. Each key-value pair in instance_init_arguments will be passed in order.
What's more, it allows you to preset the transform of the instance in the editor, which is very useful when you want to create the instance by a specific offset / rotation / scale / skew (for 2D only) based on the global transform of this node, which greatly simplifies the process of creating 2D/3D instances.