Migrating from Gaia 2021 to Gaia 2023

Applies To: Gaia (Pro) 2021 & Gaia (Pro) 2023

The 2021 and 2023 versions of Gaia are NOT directly compatible. This means you cannot directly install the newer 2023 version of Gaia over an existing 2021 installation. This is due to the following reasons:

• The file structure of the package has changed drastically
• There are installable components now in 2023 that are structured differently
• The Flora terrain detail system in 2021 was replaced with the native instanced terrain detail rendering in Unity
• Gaia 2023 requires a higher minimum unity version (2022.3)

Gaia 2021 still supports unity releases up to 2023.1, therefore should be no immediate pressure for you to change your existing project to Gaia 2023. You can however, migrate your Gaia 2021 to Gaia 2023 under the following considerations:

• You would need to use at least Unity 2022.3
• If you are using Flora, you would need to re-spawn the vegetation using Unity's GPU instanced terrain detail system instead. If you were using one of the Biomes / Spawners that were included with Gaia 2021, you could run its equivalent in Gaia 2023 and you should be all set.
  If you were designing your own spawner settings using Flora, you would need to migrate your spawner to use Unity's terrain detail system manually after the update.
• The lighting setup in Gaia 2023 has been overhauled and the lighting presets might look slightly different now
• The embedded HDRP Time of day system has been removed in Gaia 2023 - if you were using this in your project, you would need to find an alternative lighting solution for the migrated project
• Gaia 2023 does not use the older First Person and Third person controller anymore, but comes instead with integrations for Unity's newer (free) First Person and Third Person character controllers. If you were using the first or third person controller of Gaia, you would need to migrate to these new controllers after the switch.

If the above points are acceptable, you could consider migrating your 2021 project to 2023. Before you start, please make sure to back up your work so nothing gets lost in case anything goes wrong.
Here is a step-by-step description of how to migrate an existing Gaia (Pro) 2021 to Gaia (Pro) 2023:

1. In the Gaia 2021 project, delete everything under "Gaia Runtime", except the Terrain Loader Manager



2. On the Gaia Runtime object itself, remove the "Gaia Global" component:



3. Save the scene. Repeat this for all scenes that have a "Gaia Runtime" object in your project.

4. Close all scenes. If necessary, migrate to at least Unity 2022.3. Please note that Gaia does not support beta or alpha versions of Unity.

5. Delete the "Gaia" and "Flora" folder under "Procedural Worlds".



Do NOT delete "Gaia User Data" as this usually contains your entire work so far!

6. Remove the old Gaia scripting defines in the project. To do so, open Edit > Project settings > Player and look at the list of scripting defines.



you would need to REMOVE the following old scripting defines if you have them in there:

FLORA_PRESENT
GAIA_PRESENT
GAIA_2_PRESENT
GAIA_PRO_PRESENT

If you are just running Gaia alone, they should not cause any issues, but other applications may "think" the older Gaia is still installed in the project which can lead to compilation errors.
To remove those entries, use the small "-" button and click "Apply" after you sanitize the list.

7. Import the new Gaia 2023 package. You will see the setup window:



In Gaia 2023, you can install components and assets separately from the main application. You would need to install the components you want to use in the final project, some considerations:

• If you were using the Gaia Pro Assets, install "Gaia Pro Assets and Biomes"
• If you were using the Synty Sample Assets, install "Asset Samples - Synty Studios"
• If you were using the Gaia Lighting Setup, install "Runtime - Lighting Presets"
• If you were using the Procedural Worlds Sky, install  "Runtime - Procedural Worlds Sky"
• If you were using the Gaia Water, install "Runtime - Gaia Water". If you are running HDRP, you could consider switching to the Unity HDRP water as well

If you are unsure do not worry, as you can install and uninstall any component at a later time as well. Click the "Start Installation" button to start the install.

8. Open the Gaia Manager. Check the Setup tab, and perform the Gaia render pipeline switch if required (including shader installation). Check the new Project Settings panel to make sure there are no issues with the project that need your attention.



9. Open your scene, and select the Runtime Tab in the Gaia Manager.

10. Select the Runtime modules you want to add to your scene and click "Create Runtime". Your scene should now run under the new Gaia 2023 runtime setup.

11. If you were using Flora, you would now need to look to replace your vegetation. To do so, you can do the following:

a) If you were using the Gaia spawners, you can browse to the new version of the Gaia spawners in your project hierarchy, and bring them into the scene. For example, if you were running the Alpine Meadow Biome, you can find the spawner for that in the project hierarchy in the installation folder for the Biomes package:



If you select that spawner, there is an option to add it to the scene:



You can select the spawner under "Gaia Tools" and remove the existing, old Terrain Details with it, then spawn the newer vegetation:

b) If you were using your own spawner setup with Flora, you would need to migrate the terrain detail resources within to use one of unity's grass rendering systems instead, preferably the newer GPU Instanced Grass. Please note that there are fitting models and materials available in the "Asset Samples" and the "Gaia Pro Assets and Biomes" packages:





The meshes found here are pre-configured to work with the GPU instanced unity terrain detail system and can be used as resources in your custom spawners:



After migrating your Flora vegetation (if any) the migration is complete, and you can continue using Gaia with your terrains originally made in the earlier Gaia version.