Gaia 1 featured an extension system that allows other asset store publishers to integrate their assets into a scene created with Gaia. With the release of Gaia 2 / Pro there were a number of changes with the Gaia asset itself as well as with the extension system which may make previously existing extensions inaccessible. This article details what Gaia users and and extension publishers can do to restore the functionality of the existing Gaia 1 extensions in Gaia 2 & Gaia Pro.


What has changed?


There are a number of changes between Gaia 1 and Gaia 2 / Pro that might create issues in the existing Gaia extensions:


  • The stamping / spawning system is vastly different in the way it works & stores its data. The original Gaia 1 resource files and stamper / spawner setups do not apply anymore
  • Gaia 2 / Pro support multiple terrains out of the box - in Gaia 1 multiterrain was not explicitly supported, but rather something the users had to achieve with workarounds
  • The general scene structure is different, objects like the terrains and the water sit under different parent objects than before
  • Gaia Pro supports terrain loading, which means there might be terrains affected by functionality of Gaia that are currently not present in the scene
  • The lighting in Gaia Pro when using the Procedural Worlds sky is quite different and uses a time of day system, which means the lighting conditions change during runtime now.
  • Due to the changes in the functionality of Gaia the publicly accessible code available to build extensions might have changed in functionality as well.
  • There are new "scripting defines" that allow asset store publishers to detect whether Gaia 1, Gaia 2 or Gaia Pro is running in the project.


Why did the existing Gaia 1 eXtensions disappear all of the sudden?

With the release of the Gaia Pro beta, the existing Gaia 1 extensions were still available in Gaia Pro, but could cause compilation errors or would not function correctly. This could cause more harm than good when the user was confronted with a lot of error messages in the console after installation of an asset.  
The Gaia 1 extensions therefore are disabled by default now in Gaia 2 / Pro and need to be consciously enabled by the user or the publisher with the awareness that it might not function properly. If the publisher has reviewed the extension to make sure it still works or has made the necessary changes, it can be unlocked for Gaia 2 / Pro permanently by the publisher.
If you are still using Gaia 1 in an existing project, nothing should have changed for you and the eXtensions should still be available as before.


For Users: What can I do to test if an existing extension still works in Gaia 2 / Gaia Pro?

If you are an user of Gaia 2 / Pro that knows that an existing extension still works or who wants to try it out, you can do so by a slight adjustment in the extension code of the respective asset.

As always: If you are not sure about making these changes, make a backup of your project first!

The technical mechanism that makes the extensions appear is a so-called "scripting define" that will unlock code depending on whether another asset or package is installed. The existing Gaia 1 extensions were made to check and unlock when the scripting define

GAIA_PRESENT

was set in the project. You can see what scripting defines are active in your project under Edit > Project Settings > Player > Scripting defines. Do NOT edit these manually as this might create unforeseen consequences.


To unlock older Gaia 1 extensions in your project, you need to look for the extension code in the respective Asset and change the code to be unlocked by GAIA_2_PRESENT rather than GAIA_PRESENT (GAIA_2_PRESENT will work for both Gaia 2 and Gaia Pro)

To find the extension code, you can either manually look for the extension code in the asset scripts, usually the file has Gaia in the name in one way or another, here is Aquas 2020 as an example:


If you can't find the extension code by the obvious filename, you can just search for the term "GAIA_PRESENT" in all of the .cs script files of the extension. The most text editors have a "Find in Files..." functionality to do searches across an entire directory and in specific file types. The Visual Studio version that comes with Unity can do this as well.

When you have located the extension code, replace all occurrences of 

#if GAIA_PRESENT

with 

#if GAIA_2_PRESENT

if this is done in Visual Studio or any other IDE you should see the code portions "unlocking" directly:


Save the file and re-open the Gaia Manager. You should see the extension appearing now.


If you are running into issues, you can revert your edits. The extensions and the errors it causes should disappear again. While you will not be able to use the extension until it is updated by the publisher, please note that Gaia creates unity standard terrain. You should therefore still be able to use the other asset together with Gaia when you pretend that the terrain is just a terrain that you would have created manually without the help of Gaia.

For example, any sky or water water asset that you use should work on a terrain that was made manually in Unity - if you follow the steps that are necessary for that on a scene with a Gaia terrain, the asset should still function the same, so the missing extension should not mean that you can't use the asset with Gaia anymore.

For Publishers: What do I need to know to create extensions from scratch in Gaia 2 / Gaia Pro

If you have not made an extension for Gaia 2 / Gaia Pro yet, or need a refresher on this topic, please see our guide on how to create eXtensions.

For Publishers: What do I need to know to make my existing Gaia 1 extensions work in Gaia 2 / Pro?

Scripting Defines

Most importantly, Gaia now uses 3 different scripting defines:

GAIA_PRESENT = set when Gaia 1 is installed in the project
GAIA_2_PRESENT = set when Gaia 2 or Gaia Pro is installed in the project
GAIA_PRO_PRESENT = set when Gaia Pro is installed in the project

With those additional defines in place, you can now choose which version of Gaia to address with your extension. If you find that your extension still works in Gaia 2 the same as it did for Gaia 1, you could also address those two versions with the same code. Some examples:

This function / GX button would only be available in Gaia 1:


This function / GX button would be available in Gaia 1, Gaia 2, and Gaia Pro:


This function / GX button would only be available in Gaia Pro:


Gaia 2 and Gaia Pro mostly share the same code base. There should be no need to tailor one extension for 2 and then another for Pro, unless you want to utilize very specific features that are available in Pro only.

The Utils class was renamed to GaiaUtils

The "Utils" class that came with Gaia was renamed to GaiaUtils for technical reasons, if you are using any functions from Utils in your extension code, please rename / refactor it to GaiaUtils instead.

How to set up pre-defined spawner settings

Gaia 1 had its own tools for exporting spawner settings into an extension. The bad news is this tool and the exported settings are not compatible with Gaia 2 / Pro anymore. The good news is that Gaia 2 / Pro makes it much easier to save spawner settings directly without any extra tools, and these saved settings can be loaded into a scene much easier as well so no dedicated exporter is needed anymore.

If you publish an art asset, and want to deliver it with pre-configured spawners for Gaia 2 / Gaia Pro, you can do so by setting up the spawner(s) with your assets as you see fit and then save the spawner settings file with the "Save / Load"-Panel in the spawner:


The resulting spawner setting file contains all the spawner configuration you just made, and can be loaded in any other spawner. When Gaia is installed in the project, the user will have the option to select the spawner file in the asset hierarchy and add it to the scene this way:


In theory this is already sufficient to supply your customers with the spawner settings you made - if you want to go the extra mile you can additionally add a button to the Gaia extensions menu to create the spawner from there as well. To do so, you only need a reference to the spawner settings file in code, and then you can create the spawner with the CreateSpawner() function of the SpawnerSettings class. Please see the attached example eXtension. It comes with an example spawner settings file, and it has such a button added in the Gaia eXtension menu so that you have a template for applying the same logic in your own extension as well.