Instanced Mesh Container

The main component designed to manage and render instances in a Unity scene.

Overview

The InstancedMeshContainer component is the primary component for managing instances of a mesh prefab, providing various methods for adding, updating, and querying these instances. It handles rendering, culling, and other operations necessary for efficiently managing large numbers of instances in a scene.

Key Features

• Instance Management: Add, update, and remove instances.

• Transform Updates: Update the position, rotation, and scale of instances.

• Querying: Perform various queries to find instances within specific bounds or rays.

• Linked Objects: Manage linked GameObjects for instances.

• Event Handling: Handle changes to the container with events.

• Instance Properties: Manage custom properties for instances.

• Enable/Disable Instances: Control the visibility of individual instances.

Properties

• Instance Count: The total number of instances in the container.

• Prefab: The mesh prefab used as the prototype for all instances.

• Prototype: The InstancedPrototype attached to the prefab.

Usage Example

Here's an example of how to use the InstancedMeshContainer component in a script:

using UnityEngine;
using Unity.Mathematics;
using MA.Mathematics;
using MA.Flora;

public class Example : MonoBehaviour
{
    public InstancedMeshContainer meshContainer;

    void Start()
    {
        // Add an instance
        int instanceIndex = meshContainer.AddInstance(new float3(0, 0, 0), quaternion.identity, new float3(1, 1, 1), Space.World);
        
        // Update the position of the instance
        meshContainer.UpdateInstancePosition(instanceIndex, new float3(1, 1, 1), Space.World);

        // Query instances within bounds
        AxisAlignedBox bounds = new AxisAlignedBox(new float3(-1, -1, -1), new float3(2, 2, 2));
        NativeArray<int> instancesInsideBounds = meshContainer.GetInstancesInsideBounds(bounds, Space.World, Allocator.Temp);

        // Clean up
        instancesInsideBounds.Dispose();
        
        // Move the container
        container.transform.position = new Vector3(0, 10, 0);
        
        // Required at runtime to notify the container that it has moved
        container.MarkTransformDirty();
    }
}

Scene Hierarchy Operations

The InstancedMeshContainer includes various menu item operations accessible through the Unity Editor to manage instanced mesh containers:

Convert to Instances

Description: Converts selected GameObjects to instances managed by an InstancedMeshContainer.

Menu Path: GameObject/Convert to Instances (Flora)

• Functionality: This operation converts the selected GameObjects into instances managed by an InstancedMeshContainer. The selected objects are grouped under a new container, allowing for efficient management of these instances.

• Usage: Useful for optimizing the scene by reducing the overhead of individual GameObjects.

Split Containers

Description: Splits the selected InstancedMeshContainer into smaller containers based on bounds.

Menu Path: GameObject/Split Container(s) (Flora)

• Functionality: This operation splits the selected InstancedMeshContainer into four smaller containers, organized spatially by bounds. Empty space within the original container is discarded, resulting in more efficient and manageable instances.

• Usage: Ideal for performance optimization and better spatial organization of instances within the scene.

Combine Containers

Description: Combines selected InstancedMeshContainer objects into a single container.

Menu Path: GameObject/Combine Containers (Flora)

• Functionality: This operation merges multiple selected InstancedMeshContainer objects into a single container. This helps in reducing the number of containers and simplifies the management of instances within the scene.

• Usage: Useful for consolidating instances to reduce the complexity of the scene hierarchy.

Convert Instances to GameObjects

Description: Converts instances managed by the InstancedMeshContainer back to regular GameObjects.

Menu Path: GameObject/Convert Instances To GameObjects (Flora)

• Functionality: This operation converts instances within an InstancedMeshContainer back into individual GameObjects. This removes the container and returns your instances back into regular GameObjects.

• Usage: Useful when detailed editing or management of individual instances is required, beyond what is possible within the container.

Detailed Documentation

Instance Management

Adding Instances

You can add instances to the container using various methods:

• AddInstance(float3 position, quaternion rotation, float3 scale, Space space): Adds a new instance with the specified position, rotation, and scale.

• AddInstance(float3 position, quaternion rotation, Space space): Adds a new instance with the specified position and rotation.

• AddInstance(float3 position, Space space): Adds a new instance with the specified position.

• AddInstance(in LocalTransform transform, Space space): Adds a new instance with the specified transform.

• AddInstances(ReadOnlySpan<LocalTransform> instances, Space space): Adds multiple instances at once.

Removing Instances

Instances can be removed using the following methods:

• RemoveInstance(int instanceIndex): Removes the instance at the specified index.

• RemoveInstances(ReadOnlySpan<int> instancesToRemove, bool alreadyReverseSorted = false): Removes multiple instances.

Updating Instances

Instances can be updated using the following methods:

• UpdateInstancePosition(int instanceIndex, float3 position, Space space): Updates the position of the instance.

• UpdateInstanceRotation(int instanceIndex, quaternion rotation, Space space): Updates the rotation of the instance.

• UpdateInstanceScale(int instanceIndex, float3 scale, Space space): Updates the scale of the instance.

• UpdateInstanceTransform(int instanceIndex, float3 position, quaternion rotation, float3 scale, Space space): Updates the transform of the instance.

• UpdateInstanceTransforms(int startInstanceIndex, ReadOnlySpan<LocalTransform> newTransforms, Space space): Updates multiple instance transforms starting at the specified index.

• UpdateInstanceTransforms(ReadOnlySpan<int> instances, ReadOnlySpan<LocalTransform> newTransforms, Space space): Updates the transforms of the specified instances.

Querying Instances

The component provides methods for querying instances:

• CalculateBounds(Space space): Calculates the bounds of all instances in the container.

• AnyInstanceOverlapsRay(Ray ray, Space space, out int hitInstanceIndex): Checks if any instances overlap with the specified ray.

• GetInstancesOverlappingRay(Ray ray, Space space, NativeList<int> hitInstances): Adds the indices of all instances overlapping with the specified ray to the provided list.

• AnyInstancesInsideSphere(Sphere sphere, Space space): Checks if any instances overlap with the specified sphere.

• AnyInstancesWithinRadiusOfInstance(int instanceIndex, float radius, ReadOnlySpan<int> excludeInstances): Checks if any instances are within a specified radius of another instance.

• GetInstancesInsideBounds(AxisAlignedBox bounds, Space space, Allocator allocator): Returns a NativeArray<int> containing the indices of all instances inside the specified bounds.

• GetInstancesInsideSphere(Sphere sphere, Space space, Allocator allocator): Returns a NativeArray<int> containing the indices of all instances inside the specified sphere.

• TryGetInstanceAtPosition(float3 position, Space space, out int instanceIndex): Tries to find the instance at the specified position.

Linked Objects

The component can manage linked GameObjects for instances:

• HasLinkedObjects: Checks if any instances have linked objects.

• HasLinkedObject(int instanceIndex): Checks if the instance at the specified index has a linked GameObject.

• GetLinkedGameObject(int instanceIndex): Returns the linked GameObject for the specified instance.

• GetLinkedObject(int instanceIndex): Returns the InstancedObjectLink for the specified instance.

• AddLinkedObject(GameObject gameObject): Adds a linked GameObject as an instance.

• AddLinkedObject(InstancedObjectLink link): Adds an InstancedObjectLink as an instance.

• AttachLinkedObject(int instanceIndex, GameObject gameObject, bool teleportToInstance): Links a GameObject to an existing instance.

• AttachLinkedObject(int instanceIndex, InstancedObjectLink link, bool teleportToInstance): Links an InstancedObjectLink to an existing instance.

• DetachLinkedObject(int instanceIndex, bool removeInstance = true): Unlinks an InstancedObjectLink from an instance.

Instance Properties

The component allows you to manage custom properties for instances:

• HasInstancedProperty(string name): Returns true if the container has an instanced property with the specified name.

• HasInstancedProperty(int nameID): Returns true if the container has an instanced property with the specified name ID.

• GetInstancedProperty<T>(string name, int instanceIndex) where T : unmanaged: Returns the value of the instanced property with the specified name.

• GetInstancedProperty<T>(int nameID, int instanceIndex) where T : unmanaged: Returns the value of the instanced property with the specified name ID.

• SetInstancedProperty<T>(string name, int instanceIndex, T value) where T : unmanaged: Sets the value of the instanced property with the specified name.

• SetInstancedProperty<T>(int nameID, int instanceIndex, T value) where T : unmanaged: Sets the value of the instanced property with the specified name ID.

• SetInstancedPropertyRange<T>(string name, int startInstanceIndex, ReadOnlySpan<T> values) where T : unmanaged: Sets a range of instanced property values for the specified property name.

• SetInstancedPropertyRange<T>(int nameID, int startInstanceIndex, ReadOnlySpan<T> values) where T : unmanaged: Sets a range of instanced property values for the specified property name ID.

Enable/Disable Instances

Control the visibility of individual instances:

• IsInstanceEnabled(int instanceIndex): Returns true if the instance at the specified index is enabled.

• SetInstanceEnabled(int instanceIndex, bool enabled): Sets the visibility of the instance at the specified index.

Events

The component provides an event to handle changes:

• Changed: Event that is invoked when the instance container is modified.