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


---

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