# Instance Handle

A `FloraInstanceHandle` is a lightweight struct used to uniquely reference a single instance managed by the global [FloraSystem](https://flora.magneticarcade.com/scripts/system).

Internally, Flora stores all instances in a **Structure of Arrays (SoA)** layout.\
Handles allow you to **query**, **modify**, or **track** instances over time without needing to know their location in memory.

***

### Validity

A handle is valid only if both its `Index` and `Version` match an **active** instance in the system.

When an instance is destroyed:

* Its version is incremented
* All previously held handles to that index become **invalid**

This prevents accidental access to stale data or reused slots.

***

### Usage

Use instance handles when you need precise, efficient control over individual instances—especially in procedural workflows or runtime simulations.

#### Creating Instances

```csharp
FloraInstanceHandle handle = FloraSystem.GetOrCreate().CreateInstance(
    prefab,
    parentObject,
    position,
    rotation,
    scale
);
```

### Destroying Instances

```csharp
FloraSystem.Instance.DestroyInstance(handle);
FloraSystem.Instance.DestroyInstances(handlesArray);
```

### Checking if an Instance Exists

```csharp
bool exists = handle.Exists();
```

### Enabling or Disabling an Instance

```csharp
bool isEnabled = FloraSystem.Instance.IsInstanceEnabled(handle);
FloraSystem.Instance.SetInstanceEnabled(handle, true);
```

### Getting Instance Transform or Bounds

```csharp
float3 position = FloraSystem.Instance.GetInstancePosition(handle);
Bounds bounds = FloraSystem.Instance.GetInstanceBounds(handle);
```