Tutorial:Making Planets

From Kerbal Space Program Wiki
Jump to: navigation, search

Creating Your Own Planets

This tutorial is designed for those with a relentless, creative spirit. Those seeking a way to vent said creativity will be delighted to learn that, with the Kopernicus plugin's existence, it is now possible to modify the planetary system in Kerbal Space Program, allowing for new planets to be added and existing planets to be modified or removed entirely.

Specifications

  • Length: 15-20 minutes
  • Difficulty: Advanced
  • For Version: 1.3.X (Planets will work in 1.4, but the map exporter won't, so we'll be using 1.3 for this tutorial)

Requirements

  • Kopernicus
  • KittopiaTech
  • A text editor. Notepad can do the job, but Notepad++ is highly recommended.
  • (No, you do not need textures or image editors of any kind. In fact, if you're going to be advising SpaceEngine, I'm glaring at you.)
  • The only objects that require the use of image editors and such are gas planets and stars. Terrestrial planets do not require textures to function.

Config Files

The first step when making planets is knowing the basics of config files. Let's start by creating one! For Notepad users, simply open up Notepad, then head to File -> Save As. Navigate to a location that you will be creating your mod at. Recommended is to create a folder for your mod somewhere (your desktop, for example) and using that folder to store all of your planet pack's data. We'll go over organizing said data later, for now, let's focus on not cluttering the hard drive and storing all mod info in a similar location.

Once you have settled on a nice saving location, write the name of your planet and remove the .txt as we will not be saving in this format. Add .cfg behind it, and select All Files in the drop-down menu following Save as type

For this tutorial, we will be making a planet called Tutora. So, in this case, we would write Tutora.cfg. The file name is actually not that important, but it's recommended to name config files properly so that you know just from the name what it contains.

Now we should have a .cfg file. Let's get to editing it!

Firstly, there are two kinds of config entries that you must memorize. The first is called a 'Config Node'. These appear as follows:

Orbit { ... }

As you can see, the name of the node is followed up by an opening bracket, which is in turn followed up by the node's contents, then lastly - and this is very, very important - the closing bracket. (Notepad++ automatically highlights opening and closing bracket pairs, which is why it is pretty much industry standard when making planets.)

The other kind of config entry is called a 'Config Value', and these appear as follows:

semiMajorAxis = 19000000

As you can see, a config value is always in the format of 'X = Y', where X is the name of the Config Value and Y is the data assigned to it. Y can be many different kinds of data, for example a line of text (a 'string', as it is called in programming languages), a whole number (also known as an integer), or a number with decimals (also known as a 'float' or a 'double', depending on the situation).

Making planets is largely the product of simply placing the correctly named nodes in the right locations, and supplying the right config values with the right data.

Module Manager Syntax

Contrary to what some might expect, we are not actually writing a piece of code for Kopernicus. Rather, Kopernicus internally has a config file, which we will be altering - and this is very important - indirectly. We will be using the 'Module Manager' plugin to patch Kopernicus' config file instead. This way, users can add and remove planet packs at will without having to go into the config files and swapping things out manually.

Although writing configs largely comes down to Nodes and Values, there are several handy commands that you can leave in your code for ModuleManager to use.

Let's go over a few.

@Orbit { ... }

The @ operator means 'edit'. In the above example, instead of declaring a node named 'Orbit', we are instead telling Module Manager to patch an already existing Orbit node. Note that this will not randomly edit an Orbit node - only one in the exact same location, in another file. (IE the parent nodes of the node marked for editing must match those of the target node in terms of name)

!Orbit {}

The ! operator differs in use. In the above example, we tell Module Manager to remove the Orbit node. We do not need to specify anything in the brackets, just add them to inform Module Manager that we are targeting a NODE, not a VALUE. Another case for the ! operator is conditioning:

@Kopernicus:NEEDS[!OPM] { .. }

Above, you can see that we edit the 'Kopernicus' node. However, we have added the 'NEEDS' condition to it. The above code, when translated to English, basically means:

Edit the config node Kopernicus with the below changes, BUT only do so if the tag named OPM is NOT present.

Note that 'not' is written in capital letters. This is because I would like to draw your attention to that word. Rather, the fact that, if we were to remove the ! operator from the above code example, we would have to remove the 'NOT' word in the translation. Ergo:

NEEDS[OPM] = only patch when the tag 'OPM' is present
NEEDS[!OPM] = only patch when the tag 'OPM' is NOT present

But what are these 'tags' that I have mentioned thrice thus far? Tags can be targeted by Module Manager conditions, and can be declared in many ways: - Folders directly inside the GameData folder of your KSP directory can be targeted as a tag. - Tags can be declared with the :FOR[X] condition, where X is the name of the tag

And that brings us to the next condition: FOR.

@Kopernicus:FOR[Bob] { ... }

FOR on it's own does not do anything, it is merely a marker for other conditions, namely BEFORE, AFTER and NEEDS. Let's call the config file containing the above node 'File A'. In that case, making config edits with conditions will have the following effects:

BEFORE[Bob] = The patch is applied before the patch declared in File A (which is marked as 'FOR[Bob]', remember!) is applied.
NEEDS[Bob] = The patch is only applied if File A (or another file declaring the tag Bob through the use of FOR) is present.
NEEDS[!Bob] = The patch is only applied if the tag 'Bob' is not declared anywhere.
AFTER[Bob] = The patch is applied after the patch declared in File A (or any other file declaring the tag Bob through the use of FOR)

And lastly, a more advanced condition, especially handy when editing a specific node of which there are multiple.

!Atmo:HAS[#name[Duna]]{} (Taken from here with lots of thanks.)

As you can see, we are removing the config node named 'Atmo', but we have the HAS condition preventing the deletion of every single node named 'Atmo'. The HAS condition limits the effect of a patch to config nodes that meet the declared condition. In the above example, each Atmo node is checked if it contains a Config Value named 'name', with an assigned value of 'Duna'.

Planetary Nodes

Before we start making planets, let's go over the config structure.

The first thing that we want to do is edit the Kopernicus Config Node. So let's open up the config we made earlier. Remember that we will be making a planet called Tutora.

@Kopernicus:FOR[Tutora] { }

The observant among you have noticed that we are declaring this config with the tag 'Tutora'. This means that we can specify a loading order for config files (should we need this later) by marking patches with AFTER, BEFORE, and NEEDS.

Every celestial body has its data stored in a node called 'Body'. There can be multiple Body nodes per config, but only one planet per Body node.

Let's add the Body node to the above start.

@Kopernicus:FOR[Tutora] {

   Body
   {
       name = Tutora
   }

}

I have also added the 'name' Config Value real quick. The 'name' Config value declares the name that the celestial body will wear, both internally and in-game (unless otherwise specified).

Inside the Body node of Tutora, we can add a variety of Config Nodes. Let's go over a few.

Debug {} Debug stores data for debugging planets, for example whether or not we want Kopernicus to generate a cache file.

Properties {} Properties stores most of our planet's physical properties (mass, radius, gravitational acceleration, rotation period, whether or not our planet is tidally locked, et cetera) as well as some miscellaneous items such as the in-game description, the science multipliers, and the timewarp altitude limiters.

Orbit {} Orbit stores the data related to the planet's placement within the Kerbal universe, or rather, the path that it will follow through said universe.

Template {} Template allows you to clone a stock planet. If you choose a template, anything you declare in your config will be applied as a patch to a copy of that template's config file. Note: you are not altering the stock planet itself, rather Kopernicus clones it and applies the data you specified to that clone. Using a template is highly recommended. In the Template node, you can also do some rather interesting things, such as removing PQSMods from the template planet (we'll go over what in the world PQSMods are later), removing the ocean of the clone, or removing the atmosphere of the cloned planet.

Atmosphere {} Atmosphere stores all of the information regarding a planet's atmosphere. Not just the altitude limiter, but also physical and chemical properties such as the adiabatic index (used for calculating the speed of sound), the molar mass (used for calculating the density), the temperature-height profile, and many other things.

Ocean {} The Ocean node stores all data regarding a planet's oceans. If a planet's configuration does not contain an Ocean node, it will not have oceans.

ScaledVersion {} Because keeping an entire planet loaded is rather taxing, KSP cleverly unloads the planet should the camera go too far from the planet, and instead will load in a relatively low-poly representation. Through ScaledVersion we can edit this representation. Essentially, ScaledVersion is in charge of making our planet look good from afar (such as in the Map View)

PQS {} PQS stands for Procedural Quad Sphere, and is the kind of terrain KSP uses for its planetary surfaces. The PQS node contains all of the data regarding our planet's actual terrain. It is therefore, in essence, the counterpart to ScaledVersion. Note that non-terrestrial objects such as Jool and the Sun lack the PQS node and thus a Quad Sphere, which is why they have no solid surface.