> 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/rendering/static-spatial-caching.md).

# Static Spatial Caching

Precompute spatial classification for static instance containers and terrain trees.

Static Spatial Caching precomputes culling-grid placement for eligible static content. It reduces scene initialization work but does not change runtime culling.

## Enable static spatial caching

1. Open **Edit > Project Settings > Graphics > Flora > Editor**.
2. Enable **Static Spatial Caching (Experimental)**.
3. Save the scene.
4. Select the [Scene Settings](/scripts/scene-settings.md) object and review the **Static Spatial Cache** status.

Use **Window > Flora > Rebuild Scene Spatial Cache** to rebuild manually.

## Eligible content

* A `FloraInstanceContainer` whose GameObject is marked Static, has a prefab, contains at least one instance, and does not opt out.
* Terrain trees owned by an enabled `FloraTerrainProvider` that does not opt out.

Terrain details are not eligible. They are generated as transient GPU data and do not use static spatial caches.

## Per-owner modes

Instance containers expose **Static Spatial Cache**. Terrain Providers expose **Tree Spatial Cache**.

| Mode       | Behavior                                                           |
| ---------- | ------------------------------------------------------------------ |
| `Auto`     | Participates while the project-wide setting is enabled.            |
| `Enabled`  | Explicitly participates while the project-wide setting is enabled. |
| `Disabled` | Never contributes data to the cache.                               |

The project setting must be enabled for both `Auto` and `Enabled`.

## Generated asset and rebuilds

For a scene named `Forest.unity`, Flora writes `Forest.FloraSpatialCache.bytes` beside the scene. Keep this asset in source control with the scene.

Flora rebuilds when settings change, a scene is saved, Play mode starts, or a scene enters a Player build. Rebuild controls are also available in the related inspectors.

The Scene Settings inspector reports one of these states:

| Status               | Meaning                                                 |
| -------------------- | ------------------------------------------------------- |
| **Unavailable**      | Save the scene under `Assets` before building a cache.  |
| **No Eligible Data** | The scene has no eligible containers or terrain trees.  |
| **Not Built**        | Eligible content exists, but no cache has been created. |
| **Out Of Date**      | The cache does not match the current eligible content.  |
| **Up To Date**       | Every eligible payload has current cache data.          |

## When not to use it

Enable it only when profiling shows meaningful scene initialization cost. It does not improve runtime rendering performance.