nathan's email about planets in SR2

Hi Gregory. Unfortunately we do not have much in the way of documentation yet on how all the planet stuff works. Its something we would like to work on, but we just haven't had much time yet with everything else we got in work at the moment. I can try and provide a bit of info to get you started if you are wanting to do some planet work prior to official planet building stuff being released.

First of all, our code should be mostly documented (useful documentation not guaranteed...). You can get to this by downloading Unity & Visual Studio, importing our mod tools package in to a Unity project, then using intellisense in Visual Studio to browse our code & documentation. The planet modifier stuff is mostly in the 'ModApi.Planet.Modifiers.VertexData' namespace. For example, if you open up Visual Studio from a Unity project that imported our mod tools package, you can then type the following in VS 'ModApi.Planet.Modifiers.VertexData.DebugVisualize', and then, selecting the 'DebugVisualize' word, hit F12 to be taken to a page in VS that shows the documentation for the class and various fields used by the class.

I'll try to make an attempt to explain how we use the planet modifiers to generate planets. Its a little complicated and doesn't always seem to make a lot of sense at times, so I apologize in advance...

First of all, modifiers are executed in a series of passes. I believe it goes something like this:

1) Biome Pass - Common Modifiers
2) Height Pass - Common Modifiers
3) Height Pass - Biome Specific Modifiers
4) Height Final Pass - Common Modifiers
5) Final Pass - Common Modifiers
6) Final Pass - Biome Specific Modifiers

Here is our code documenation on the pass types:

    /// <summary>
    /// The 'Biome' pass which runs first.
    /// This pass is responsible for setting the biome strength values.
    /// It may also set any other output data as well.
    /// The input position is available in this pass but the normal is not available.
    /// This pass is only ran for common modifiers and will not be executed for biome specific modifiers.
    /// </summary>
    Biome,

    /// <summary>
    /// The 'Height' pass which runs second.
    /// This pass runs after the 'Biome' pass and is responsible for setting the height value.
    /// It may also set any other output data as well other than the biome strength values.
    /// The input position is available in this pass but the normal is not available.
    /// This pass is ran for common modifiers first and then executed for biome specific modifiers second.
    /// </summary>
    Height,

    /// <summary>
    /// The 'HeightFinal' pass which runs third.
    /// This pass is just like the Height pass but it runs after it and is useful for
    /// common modifiers that need to run after biome specific height pass modifiers.
    /// The input position is available in this pass but the normal is not available.
    /// This pass is only ran for common modifiers and will not be executed for biome specific modifiers.
    /// </summary>
    HeightFinal,

    /// <summary>
    /// The 'Final' pass which runs last.
    /// This pass runs after all other passes and is responsible for setting any remaining vertex data that has not been set.
    /// It may set any data other than the biome strength values and the height value.
    /// The input position and the normal position are both available in this pass.
    /// This pass is ran for common modifiers first and then executed for biome specific modifiers second.
    /// </summary>
    Final,


Another key thing to keep in mind is that modifiers should be executed (within a pass), in the order they appear in the game object hierarchy (tree structure). This is based off the hierarchy parameter on a modifier in the XML. Typically, this means that the modifiers are executed in the order in which they appear in the XML, but this may not be true if you have a few modifiers in a /Foo/ hierarchy, then add a few modifiers in a different hierarchy like /Bar/, then resume adding modifiers in the /Foo/ hierarchy (All of /Foo/ would be executed first). Other than potentially having an impact on execution order, hierarchy is mainly used for grouping modifiers with a common goal to make things easier to develop, so they are not necessarily needed. The 'name' attribute is also one of those things to help you identify stuff as you develop, but the runtime doesn't really care about.

Another key aspect of how things work is the whole concept of these 'data' values used by the modifiers. Basically, you have an array of 10 doubles to store data in. When a modifier has attributes like inputDataIndex="2" and outputDataIndex="4", it basically means that the input value will be the double at index 2 in the data array and the output will go into the data array at index 4. If memory serves me correctly, I believe these data values are persistent not only between modifiers, but also between passes (so storing a value at index 9 in the Biome pass, will allow you to use that value later in the Height pass for example). Sometimes we store a value in the data array and reuse it several times. Other times, we store a value there, then read it with the next modifier, then overwrite it with something completely different later on.

One gotcha with the data array is for biome specific modifiers. I believe they have a temporary set of data values that are maintained only for a specific biome within a specific pass. When the next biome in the pass is executed, those values may all be overwritten by the current biome. The common data array should still be maintained though.

One modifier I find incredibly useful when making planets is the 'VertexData.DebugVisualize' modifier. I believe we have left a few instances of it in the current planet XML (disabled by default). This modifier can be used to visualize the data in a particular index of the data array as color values. This was vital in the development of our planets.

Some of our planets are pretty complicated... It might actually help to start completely from scratch with a planet and build it piece by piece as you go. I sometimes have a hard time deciphering what each modifier of one of our planets does or how it does it. When they get that big and complicated, they can become a bit of a house of cards, and easy to break everything with even small tweaks (part of the problem is that we reuse a lot of data from previous modifiers for the sake of performance, so things can become pretty interconnected and easy to break).

Sorry for the giant wall of text. Hopefully it helps a bit (I know its pretty confusing..). If you have any questions about any of it or about how any of the modifiers work, let me know. I'll do what I can to respond, but we are pretty busy so I apologize in advance if there is some delay or if something falls through the cracks.

--Nathan