| On this page |
The plug-in allows to instance generated or existing geometry easily.
Three types of instancing are supported:
-
Packed Primitives
-
Object Instancers
-
Point Cloud Instancing
If wanting to instance generated geometry (by the HDA), then it is recommended to use Packed Primitives. Instead if wanting to use instances of already existing Unity geometry (prefabs), then it is recommended to use Point Cloud Instancing.
The following shows a cube in Unity being instanced:
Packed Primitives ¶
Packed primitives are essentially primitives that live inside of SOPs and contain one or more primitives with their own transforms. Packed primitives can contain other packed primitives allowing to have a full transform hierarchy completely inside of SOPs. The benefit of using packed primitives is that only one copy of the geometry is stored in memory for all the instances.
In Unity, a packed primitive output (GameObject) is instantiated such that its mesh data is shared, rather than copied, for each instance. Also, GPU Instancing is automatically enabled on the generated Materials to allow for batched rendering.
A simple way to use this method is to use a Copy To Points SOP with the Pack and Instance option enabled. You also have the option to use Packed Geometry before Merging on Inputs.
Object Instancers ¶
Instancers can also be created using the instance Object node. While this is a valid instancing method, it is recommended to use Packed Primitives for instancing generated output.
The above shows input field for an object instancer. If multiple objects are specified, they will be treated as a single object and instanced.
Attribute Instancers ¶
Objects within an HDA can be instanced via the special instance point attribute in the instancer Object node.
Point Cloud Instancing ¶
The simplest way to instance existing Unity prefabs or assets (e.g. FBX models) through an HDA is by generating only points in a geometry (i.e. no primitives), and using the special unity_instance attribute. This point or detail attribute should be string-type, and contain the path in Unity project of the asset to instance.
Path should be relative to the project Assets folder (e.g. “Assets/Prefabs/Hero.prefab”). Note that it will be faster to load prefab assets from the Resources/ folder, than from the Assets/ folder. Assets placed in Resources/ folder can be specified via a relative path from Assets/, Resources/, or simply its file name without extension.
Example of supported paths for assets placed in Resources/ folder:
-
Assets/Resources/cube.prefab
-
Resources/cube.prefab
-
cube
Additionally, a MeshCollider can be set for each instance by using the collision_geo string attribute. This attribute value should point to a Unity mesh asset in the Assets/ directory. If there is an existing collider on the instance object, it will be replaced.
It is recommended to use orient attribute for specifying the orientation of the instance. It might be necessary to remove the N attribute for proper orientation as well.
Overriding Instance Inputs ¶
You can expose the Object Path Input parameter allowing to override the geometry being instanced via Inputs.
For attribute instancers, if more than 1 GameObject is added to the input list, they will be randomly used for instancing. This provides automatic variety for instances.
Instance Names ¶
The default convention for the names of the gameobjects for instances is: _geoname_Instance index_. This would produce something like “Cube_Instance2” for the second instance of geo node named “Cube”. To override this behaviour, a string attribute named instance_prefix can be used to set the prefix part of the name. In the example, this would replace the geo node name “Cube” with the value in the instance_prefix attribute. The attribute must be Detail or Point owned.
Single instance prefix using Detail attributes ¶
When using a Detail attribute to set the instance prefix, all instances will have the same prefix.
Multiple instance prefixes using Point attributes ¶
Using Point attribute, each instance name prefix can be set individually.
Splitting Instancers ¶
There are some cases where you may want to split instancer outputs to multiple components. This could be to assign different materials to each instancer, or to get a finer grain control on the actors generated when baking.
This can be achieved by using the unity_split_attr string attribute. This attribute’s value should be set to the name of another attribute, whose values will be used to control the splitting. (a separate instancer component will be created for each individual value of that attribute).
Here is an example of an HDA that splits instancers based on the unity_material attribute:
