> 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/getting-started/upgrading-from-6-3-35.md).

# Upgrade from 6.3.35

Upgrade projects and runtime code from Flora 6.3.35.

Review these changes when upgrading runtime code or serialized settings.

## Instance relationships

Instance relationship APIs now use three concrete roles: `Prefab`, `RenderDefinition`, and `Owner`.

| Previous API                                | Replacement                                   |
| ------------------------------------------- | --------------------------------------------- |
| `FloraInstanceFilter.ByIdentitySource(...)` | `FloraInstanceFilter.ByPrefab(...)`           |
| `FloraInstanceFilter.ByRenderSource(...)`   | `FloraInstanceFilter.ByRenderDefinition(...)` |
| `IdentitySourceGameObjectID`                | `Prefab`                                      |
| `RenderSourceGameObjectID`                  | `RenderDefinition`                            |
| `OwnerGameObjectID`                         | `Owner`                                       |
| `GetInstanceIdentitySource(...)`            | `GetInstancePrefab(...)`                      |
| `GetInstanceRenderSource(...)`              | `GetInstanceRenderDefinition(...)`            |

The previous names remain as obsolete compatibility aliases until a future version. Serialized `FloraInstanceFilter` fields migrate automatically. Constructor named arguments use `prefab`, `owner`, and `renderDefinition`.

`GetInstancePrefab(...)` now returns null for scene-only renderers instead of returning the scene object as an identity fallback. Use `GetInstanceRenderDefinition(...)` when you need the object supplying render data.

See [System](/scripts/system.md#instance-relationships) for the role definitions and common mappings.

## Rendering configuration

* **Enable GPU Occlusion Culling** replaces **Disable GPU Occlusion Culling**. Serialized behavior is preserved.
* Renderer, LODGroup, Terrain, and Camera settings replace the removed scene-level feature gates.
* Range-density controls now belong to [`FloraRenderSettings`](/scripts/render-settings.md).

Writable Volume Profiles migrate `FloraDensitySettings` automatically. `FloraRenderSettings` wins conflicting overrides. Read-only profiles and `GetGlobalDensitySettings()` remain compatible with 6.x.

## Terrain details

Terrain details are transient GPU data. They have no `FloraInstanceHandle` and do not appear in instance-handle queries. `ByDetails()` and `TerrainDetail` are obsolete and never match.

Code that previously used `ByDetails()` to identify nearby vegetation should use the dedicated terrain-detail query API:

| Previous workflow                                                    | Replacement                                                                                                                                                                                                    |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Query detail instance handles with `FloraInstanceFilter.ByDetails()` | Create a `FloraTerrainDetailQuery` for the required prototype and call `FloraSystem.ScheduleTerrainDetailQuery(...)`, `RunTerrainDetailQuery(...)`, or submit a batch with `ScheduleTerrainDetailQueries(...)` |
| Inspect an instance to determine its prototype                       | Read `FloraTerrainDetailQueryResult.Prototype`                                                                                                                                                                 |
| Count matching detail instances                                      | Read `FloraTerrainDetailQueryResult.Count` or test `Present`                                                                                                                                                   |

For one scheduled query, Flora returns a disposable `FloraTerrainDetailQueryRequest` that references pooled result storage and exposes its completion handle. Call `Complete()` to retrieve the result, then dispose the request. Do not copy requests. `RunTerrainDetailQuery(...)` returns one result immediately without allocating result storage. For a batch, the caller supplies equally sized `NativeArray<FloraTerrainDetailQuery>` and `NativeArray<FloraTerrainDetailQueryResult>` collections. Each query names the prototype `EntityId` it is looking for.

Queries inspect resident data without expanding terrain-detail streaming. They report `FloraTerrainDetailQueryStatus.NotResident` when an intersecting density patch has not loaded. Let normal camera streaming make the region resident, or retain a `FloraStreamingSphereHandle` created with `FloraSystem.CreateTerrainStreamingSphere(...)` for a region that must stream without a camera. Retry the query on a later frame. See [Query nearby detail prototypes](/scripts/terrain-provider.md#query-nearby-detail-prototypes) for the complete workflow.

Terrain detail streaming is automatic. The former streaming mode, responsiveness, and work-budget controls have been removed. Use `DetailUnloadHysteresisSeconds` to configure only the unload grace period.

Requested density maps are imported in coalesced patch ranges, ready patch layers are generated atomically on the GPU, and expired patches are released immediately.

See [Scene Settings](/scripts/scene-settings.md#detailunloadhysteresisseconds).

## Runtime-created instance layers

The `CreateInstance(...)` and `CreateInstances(...)` overloads accept `FloraPrefabLayerSource`:

* `Owner` uses the owner or parent layer and remains the default.
* `Prefab` uses the prefab's layer.

## Variation colors

Submit colors with `SetInstanceVariationColor(...)` or `SetInstanceVariationColors(...)`. Keep readable state in caller-owned data.

The obsolete `GetInstanceVariationColor(...)` always throws `NotSupportedException` and will be removed in the future.