> For the complete documentation index, see [llms.txt](https://flora.magneticarcade.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://flora.magneticarcade.com/scripts/system.md).

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

`FindInstancesIntersectingSphere*` and `FindInstancesIntersectingBounds*` test each instance's render bounds. Use these when you need objects whose visible bounds overlap an area, such as impact volumes, damage zones, or visibility tools.

`FindInstanceOriginsWithinSphere*` and `FindInstanceOriginsWithinBounds*` test each instance's transform origin. Use these when the position itself must be inside the area, regardless of mesh bounds size.

Both query families support:

* unfiltered queries
* `FloraInstanceFilter` queries, such as `ByTrees()`, `ByLayerMask(...)`, `ByIdentitySource(...)`, and `ByRenderSource(...)`
* prefab instance ID queries using `NativeArray<int>`
* allocation-returning overloads with an `Allocator`
* caller-owned `NativeList<FloraInstanceHandle>` overloads that clear and reuse the result list

Origin-query entry points are:

* `FindInstanceOriginsWithinSphere(...)`
* `FindInstanceOriginsWithinSphereMatching(...)`
* `FindInstanceOriginsWithinBounds(...)`
* `FindInstanceOriginsWithinBoundsMatching(...)`

```csharp
using var results = new NativeList<FloraInstanceHandle>(Allocator.Temp);

flora.FindInstanceOriginsWithinSphereMatching(filter, sphere, results);
flora.SetInstancesEnabled(results.AsArray(), false);

flora.FindInstancesIntersectingBounds(bounds, results);
```

***

## 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.FindInstanceOriginsWithinSphereMatching(filter, sphere, Allocator.Temp);

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

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

## How To Verify

* Created instances are visible and have valid handles.
* Render-bounds queries return instances whose visible bounds overlap the search area.
* Origin queries return instances whose transform position is inside the search area.
* Destroy/disable calls remove visibility and invalidate stale handles.

## Migration Note

Older `InSphere` and `InBounds` query names were replaced by the `FindInstancesIntersecting...` render-bounds query names.