There is a little discussion about the “select a planet to orbit” feature in the docs, specifically about how the calculation assumes M_{orbited} \gg m_{satellite} and may not give good results otherwise.  After all, you can’t have a massive star orbit a tiny planet. 

One thing not mentioned is that this function takes into consideration the current velocity of the parent object (the one that will be orbited).   Depending on the system you are trying to create, this may be important.


Here is an example.  Say you want to make a sun-earth-moon-like system, that you have finished entering in the starting positions, and are now at the point that you want to use this function to set the velocities of the planet and moon.  The order affects the outcome, and you’ll first want to use the function on the planet, then secondly on the moon.  This way the moon orbit will be calculated relative to the motion of the planet, which is itself in orbit.  If you first set the moon to orbit the planet, and afterward set the planet to orbit the sun, the moon orbit will be calculated relative to a stationary planet, and the final result won’t have a stable orbit.

For those that are interested, the formula for calculating the circular orbit velocity for an object assuming m \ll M is: 

\displaystyle V_m=\sqrt{\frac{G \cdot M}{d}}

where d is the distance between the two objects.  The velocity direction is perpendicular to the line connecting the two objects, and the particular perpendicular chosen determines the orbital plane.  G3D picks an orbital plane that is parallel to the xy plane.