> 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 global system that stores and manages all Flora instances.

`FloraSystem` is the global runtime API for creating, updating, querying, and destroying Flora instances.

## Access

Use `FloraSystem.GetOrCreate()` to get the active system or create one.

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

## Create and destroy instances

```csharp
FloraInstanceHandle handle = flora.CreateInstance(prefab, parent, position, rotation, scale);
flora.DestroyInstance(handle);

flora.CreateInstances(prefab, parent, handles, transforms);
flora.DestroyInstances(handles);
```

## Instance relationships

Flora tracks three distinct `GameObject` roles for each instance. The same object can fill more than one role.

| User-facing role      | API term           | Answers                                                                               |
| --------------------- | ------------------ | ------------------------------------------------------------------------------------- |
| **Prefab**            | `Prefab`           | Which prefab does the instance represent? Scene-only renderers have no prefab.        |
| **Render Definition** | `RenderDefinition` | Which object does Flora read for the renderer hierarchy, meshes, materials, and LODs? |
| **Owner**             | `Owner`            | Which scene object manages the instance's placement, lifetime, or grouping?           |

Common registration paths map these roles as follows:

| Registration path                     | Prefab       | Render Definition | Owner          |
| ------------------------------------- | ------------ | ----------------- | -------------- |
| `CreateInstance(prefab, owner, ...)`  | Prefab       | Prefab            | Supplied owner |
| Prefab-backed `FloraInstanceRenderer` | Prefab asset | Scene instance    | Scene instance |
| Scene-only `FloraInstanceRenderer`    | None         | Scene object      | Scene object   |
| Terrain tree                          | Tree prefab  | Tree prefab       | Terrain        |

Choose filters by the relationship you want to match:

* `FloraInstanceFilter.ByPrefab(prefab)` matches every instance representing that prefab, regardless of its owner or render definition.
* `FloraInstanceFilter.ByOwner(owner)` matches every instance managed by that terrain, container, renderer host, or other scene owner.
* `FloraInstanceFilter.ByRenderDefinition(renderDefinition)` matches the exact object supplying render data. This is mainly useful for advanced scene-renderer and diagnostic workflows.

Use `GetInstancePrefab(...)`, `GetInstanceRenderDefinition(...)`, and `GetInstanceOwnerGameObject(...)` to inspect these relationships for an instance handle. `GetInstancePrefab(...)` returns null for scene-only renderers.

## Enable and disable instances

```csharp
flora.SetInstanceEnabled(handle, false);
flora.SetInstancesEnabled(handles, false);
```

## Queries

Choose the query family by what must be inside the search area:

| Query                          | Tests            |
| ------------------------------ | ---------------- |
| `FindInstancesIntersecting...` | Render bounds    |
| `FindInstanceOriginsWithin...` | Transform origin |

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

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

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

Both families support:

* unfiltered queries
* `FloraInstanceFilter` queries, such as `ByTrees()` and `ByLayerMask(...)`
* prefab queries using `NativeArray<EntityId>`
* allocated results or a reusable `NativeList<FloraInstanceHandle>`

Terrain details are transient GPU data and are excluded from instance-handle queries. `FloraInstanceFilter.ByDetails()` and `FloraInstanceTypeMask.TerrainDetail` are obsolete and never match. Use the dedicated [terrain-detail query](/scripts/terrain-provider.md#query-nearby-detail-prototypes) API to test a specific prototype near a position without creating CPU detail instances.

## Runtime-created instance layers

`CreateInstance(...)` and `CreateInstances(...)` accept a `FloraPrefabLayerSource`:

```csharp
FloraInstanceHandle handle = flora.CreateInstance(
    prefab,
    owner,
    localToWorld,
    FloraPrefabLayerSource.Prefab
);
```

`Owner` uses the owner or parent layer and is the default. `Prefab` uses the prefab layer.

## Variation color

Enable `VariationColor` in `FloraAdditionalRendererSettings.AdditionalPerInstanceData`, then submit colors through Flora:

```csharp
flora.SetInstanceVariationColor(handle, new float4(1f, 0.5f, 0.2f, 1f));
```

Keep readable colors in caller-owned data. `GetInstanceVariationColor(...)` is obsolete, always throws `NotSupportedException`, and will be removed in 7.0.

## Migration Note

`InSphere` and `InBounds` were replaced by `FindInstancesIntersecting...`. See [Upgrade from 6.3.35](/getting-started/upgrading-from-6-3-35.md) for other compatibility changes.