# System

The `FloraSystem` is the global runtime API for Flora instances.

## What It Is

`FloraSystem` stores runtime instance data and provides methods to create, modify, query, and destroy instances.

## When To Use It

Use `FloraSystem` when you need runtime control (spawning, simulation updates, queries, bulk enable/disable).

## Access Pattern

Use `FloraSystem.GetOrCreate()` to guarantee an active system.

```csharp
var flora = FloraSystem.GetOrCreate();
```

***

## Core Tasks

### Create or destroy a single instance

```csharp
FloraInstanceHandle handle = FloraSystem.GetOrCreate()
    .CreateInstance(prefab, parent, pos, rot, scale);

FloraSystem.Instance?.DestroyInstance(handle);
```

### Create or destroy a batch of instances

```csharp
FloraSystem.GetOrCreate().CreateInstances(prefab, parentObj, handlesArray, transformsArray);
FloraSystem.Instance?.DestroyInstances(handlesArray);
```

### Control instance visibility

```csharp
FloraSystem.Instance?.SetInstanceEnabled(instanceHandle, false);
FloraSystem.Instance?.SetInstancesEnabled(instanceHandleArray, false);
```

### Query instances by sphere or bounds

```csharp
var inSphere = FloraSystem.Instance?.FindInstancesIntersectingSphereMatching(filter, sphere, Allocator.Temp);
var inBounds = FloraSystem.Instance?.FindInstancesIntersectingBoundsMatching(filter, bounds, Allocator.Temp);
```

***

## Example

```csharp
var flora = FloraSystem.GetOrCreate();

var handles = new NativeArray<FloraInstanceHandle>(100, Allocator.Temp);
var transforms = new NativeArray<FloraInstanceTransform>(100, Allocator.Temp);

for (int i = 0; i < 100; i++)
    transforms[i] = FloraInstanceTransform.FromPositionRotationScale(RandomPosition(), quaternion.identity, 1f);

flora.CreateInstances(grassPrefab, owner, handles, transforms);

var sphere = new BoundingSphere(playerPos, 10f);
var filter = FloraInstanceFilter.ByIdentitySource(grassPrefab);
using var nearby = flora.FindInstancesIntersectingSphereMatching(filter, sphere, Allocator.Temp);

flora.SetInstancesEnabled(nearby.AsArray(), false);

handles.Dispose();
transforms.Dispose();
```

## How To Verify

* Created instances are visible and have valid handles.
* Query returns expected subset.
* Destroy/disable calls remove visibility and invalidate stale handles.

## Migration Note

Older names like `FindInstancesInSphereMatching` and `FindInstancesInBoundsMatching` were replaced by `FindInstancesIntersectingSphereMatching` and `FindInstancesIntersectingBoundsMatching`.


---

# 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/system.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.