# Instance Handle

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

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);
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://flora.magneticarcade.com/scripts/instance-handle.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.