PUBLISHER: PROCEDURAL WORLDS
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 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 (with over 450,000 views in the Gaia forum, and a position that is on the asset store home page more often than off 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:
The way it actually works is via the detection of an extension script that has been specially designed to be detected by Gaia, and then exposed as a series of menu items in the Extensions tab in the Gaia Manager interface, where it can be used with your scene. In the example above, the extension makes it really easy to make use of the Desktop Ground Cover Package from SpeedTree.
You can create extensions in two ways – the first via the Extension Exporter under the Utilities menu, which is good for Art Assets. And the second is manually, which is good for software assets and tools.
ART based Extensions
Art based extensions are extensions that describe assets that can be spawned such as terrain textures, grasses, trees and game objects / points of interest.
The benefit of art based extensions is that you can snapshot the resources and spawners for your art assets at a point in time, and from there you can use them as a backup, or share them with others. What happens is that when that script, and those art assets are dropped into another project Gaia can then expose them for use via the GS / INSTALLED tab. One of the cooler things about this is that even if the art assets are installed into a different directory than the one you installed it into, Gaia will still find them in your project. Note – you need to use unique file names for Gaia to be able to locate the assets without any manual intervention.
First set up and test resources and the spawners that use them. Make sure that they work well on a range of different terrain types. Then select Extension Exporter from the Utilities Menu to display the extension exporter.
Put in your publisher name, and your extension name, and modify the about box content to show something relevant to your extension. Then drag each of the Spawners that you want to be included onto the extension. The extension manager will pick up both the Spawner, and the resources that it is using.
Finally, when you are done, hit the Save Extension button and the next extension will be created. Give Unity a few moments to compile the extension, and the new extension will now be visible in the GX / INSTALLED tab within the Gaia Manager.
You can find the script in the GaiaExtensions directory in your project. This script is now an indelible backup of your resources and spawner configurations, and can easily be shared with others.
Note – to test – hit the ‘Create Gaia Resource’ button. This will create the new resource file from the script and also put it in the GaiaExtensions folder. You can then create the related spawner and test.
If you are creating assets, then include the script with your asset, and anyone who installs that asset, and also has Gaia, will be able to leverage your assets easily within their scenes.
If you would like to leverage the Gaia Compatible logo, and benefit from the exposure that Gaia provides then please contact me vie the Unity forums. I will be happy to help you fine tune your extensions, and to show them off and promote them.
CODE Based Extensions
Code based extensions are extensions for tools. These are generally a custom thing, and makes it easy to leverage your tools in a Gaia Scene. 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.
The compilation define – wrap it around your entire code base:
#if GAIA_PRESENT && UNITY_EDITOR
your namespace in here
This will ensure that the script will only compile in the editor (i.e. no run time errors), and if Gaia is present.
your class in here
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:
public class CameraAndLight : MonoBehaviour
The class name should be the name of the asset package and in camel case.
The publisher name:
public static string GetPublisherName()
return “Procedural Worlds”;
Return the asset package publisher name as you would like it to appear in the GX / Installed tab.
The package name:
public static string GetPackageName()
return “Camera And Light”;
Return the package name as you would like it to appear in the GX / Installed tab.
The package integration menu buttons:
public static void GX_About()
EditorUtility.DisplayDialog(“About Camera and Light”, “Camera and Light was put together for your convenience with assistance and coaching from Josh Savage (@TerrainBuilder), Don Anderson (@Olander), and the Unity community as a whole.”, “OK”);
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.
GaiaSceneInfo info = GaiaSceneInfo.GetSceneInfo();
This method call will populate a GaiaSceneInfo object with the following settings from your scene:
public Bounds m_sceneBounds = new Bounds();
public Vector3 m_centrePointOnTerrain = Vector3.zero;
public float m_seaLevel = 0f;
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 CameraAndLight in Gaia/Scripts/Extensions/CameraAndLight.cs. Note this script also shows off an example of how to use standard assets using reflection. It is generally very poor form to include standard asset scripts in your own extensions as they cause conflicts when people are using different and later versions of Unity.