Both Gaia 2 and Gaia Pro allow other Asset Store developers to build Gaia eXtensions (GX) which become available in the GX tab in the Gaia Manager as soon as Gaia and the other asset are installed together in an Unity project. This article details how to create such an eXtension for Gaia 2 / Gaia Pro.
The intention of the Gaia eXtension (GX) system is to make it easier for people to get the best value out of the assets they have purchased by leveraging the power of Gaia to apply them into the scene.
The extension system has a number of benefits:
It makes it easier for users to get the best value out of their assets by leveraging the power of Gaia and its work flow to generate scenes
It can reduce support effort on both sides when you can provide the users with a simple button to set up your asset within a Gaia scene
It makes it possible for publishers of quality assets to get their assets featured as compatible assets within Gaia and this drives traffic and sales to those assets. Gaia is featured on the asset store home page often and has over 1 million views in the Unity forum and 5 million minutes of tutorial videos watched on youtube - this represents a significant opportunity to get exposure for your asset!
It drives the overall brand recognition of Gaia in the community – which in turn allows me to make Gaia more useful for users and publishers.
When detected, the extension is exposed in the Gaia Manager under GX / Installed Extensions:
How it works
The way it actually works is via the detection of an extension script that has been specially designed to be detected by Gaia. Functions within the extension script will then be exposed as a series of menu items in the Extensions tab in the Gaia Manager interface. You can control yourself which code will be executed behind those buttons when they are pressed, so you got full control about how your asset is set up within a Gaia scene.
In the example above, the Aquas extension makes it really easy to set up the Aquas water in a Gaia scene by launching its own Setup Wizard which is then pre-filled with the Information from the current scene.
Extensions in general fall under two main categories: ART based Extensions and CODE Based Extensions
ART based Extensions
Art based extensions are extensions that contain spawner setups for assets that can be spawned such as terrain textures, grasses, trees and game objects / points of interest. If, for example, you are publishing an asset pack with forest trees you can make a Gaia spawner configuration for those trees with rules how these trees should be used by Gaia.
The extension would then allow your customers to use your ready-made spawning configuration in their own projects as well.
If you want to create such an art extension with your assets, you can start 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 - you can direct the users to the spawner settings file which is part of your asset, and the users could create a new spawner with this file - done!
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 next chapter and take a look at 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.
CODE Based Extensions
Code based extensions allow you to execute your own code to integrate your asset from a button click within the Gaia Manager. An example is the placement and configuration of a Sky or Water asset into a scene. Gaia provides you with routines that you can call to get a description of the scene that you can then use to auto configure your asset.
Here are the key elements of an extension as they would appear in your code in detail. If you rather want to take a look at a complete example script, please download the example eXtension below, it contains a complete working example for you to check out.
The compilation define – wrap it around your entire code base:
This will ensure that the script will only compile in the editor (i.e. no run time errors), and if Gaia 2 (or Gaia Pro) are present.
Gaia now uses the following scripting defines that you can use:
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
Gaia 2 and Gaia Pro mostly share the same code base, so you should be able to query the presence of both Gaia 2 / Gaia Pro with the GAIA_2_PRESENT define. 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 namespace must start with Gaia.GX. in order for Gaia to recognise and use it. It is good practice to then use your publisher name and use camel case.
The class name:
The class name should be the name of the asset package and in camel case.
The publisher name:
Return the asset package publisher name as you would like it to appear in the GX / Installed tab.
The package name:
Return the package name as you would like it to appear in the GX / Installed tab.
The package integration menu buttons:
To be detected and exposed as a button, the method should be declared public static, and the method name should have GX_ prepended onto it. The method name should also be written in camel case as this will be used to determine where spaces will be inserted in the button that is generated. Your code will be called when the button is pressed.
The order in which methods are defined will control the order in which Gaia exposes them.
If you would like a group of methods to be include in a sub menu, then add an underscore in the method name for each method that will be exposed. If the under score is omitted then the button will be shown at the top level.
For example public static void GX_SubmenuName_BigButton() would be exposed as Submenu Name -> Big Button.
As a general rule you should include a GX_About method as your first method and include descriptive text about your extension.
Package scene helper method:
Gaia includes a helper method that can be used to get information about the scene which can be used to help you position and configure your extension.
This method call will populate a GaiaSceneInfo object with the following settings from your scene:
The scene bounds contains the physical bounds of your terrain.
The center point on terrain is the center of your terrain, at whatever height ground level is in your terrain.
The sea level is what Gaia is using for sea level.
Check out the attached example eXtension for a complete script that also demonstrates how to create a spawner from code.