// VertexHeightPolyhedron example
// Install: put PolyhedronPQS.dll in GameData/PolyhedronPQS/Plugins/  (needs Kopernicus and HarmonyKSP)
// Copy only the VertexHeightPolyhedron node into your own body's PQS > Mods node.
// Do not install this file as-is: it defines a whole body called MyCubeWorld. Keep it (and the
// project's source, bin and obj folders) outside GameData. Only PolyhedronPQS.dll belongs there.
//
// ---- Shape ---------------------------------------------------------------------------------
//   faces      4-30. 0, below 4, or above 30 = normal spherical body.
//   layout     Auto    4 tetrahedron, 6 cube, 8 octahedron, 12 dodecahedron, 20 icosahedron,
//                      any other count = prism (2 caps + faces-2 sides): 5 triangular, 7 pentagonal, ...
//              Prism   always a prism (6 = cube, 8 = hexagonal prism, ...). 4 can't close, so it falls back to a sphere.
//              Spread  faces spread evenly over the sphere, any count 4-30.
//   fit        Circumradius  corners touch the body radius (default, the solid sits inside the sphere)
//              Inradius      face centers touch the body radius (corners stick out)
//   rotationX/Y/Z   orientation in degrees (Unity Euler order). Default 0.
//
// ---- Irregular shapes: GeometricPreset -----------------------------------------------------
//   Instead of "faces", pick a ready-made shape:
//
//       GeometricPreset = Cylinder | Hemisphere | Torus | Capsule | Cross      (None = use "faces")
//
//   When GeometricPreset is set, "faces" and "layout" are ignored. fit, rotationX/Y/Z, smoothing
//   and every gravity option below still apply, and surface gravity follows the flat caps, curved
//   walls and so on just like it does on a polyhedron.
//
//   Each shape has its own settings node, named after the shape, written inside VertexHeightPolyhedron.
//   Every value in it is optional (the numbers shown below are the defaults). Write ONE value per
//   line, like everywhere else in a KSP config. The mod will still read a few "name = value" pairs
//   sharing a line, and will not mind letter case, but it is not how config files are meant to be written. Only the sizes relative to each other matter: "fit" scales the whole
//   shape so it matches the body's radius. The shape's axis is the body's rotation axis (north-south)
//   unless you rotate it.
//
//   Cylinder
//   {
//       verticalRadius = 1
//       steps = 0
//   }
//       verticalRadius   half the distance between the two flat caps, as a multiple of the cylinder's
//                        radius. 1 = as tall as it is wide, 0.5 = a flat disc, 3 = a tall column.
//       steps            sides around the cylinder. 0 = perfectly round, 3 to 64 = a prism with that many
//                        sides (6 = hexagonal). More steps = rounder.
//
//   Hemisphere
//   {
//       verticalRadius = 1
//       baseDepth = 0.1
//       steps = 0
//   }
//       verticalRadius   height of the dome compared with its width. 1 = a round dome, 0.5 = flattened.
//       baseDepth        how far below the center of the body the flat base sits, as a multiple of the
//                        dome's width. Small = close to an exact half sphere, larger = more than half.
//                        (Put it at or above verticalRadius and the base disappears: a full sphere.)
//       steps            facets around the dome. 0 = smooth, 3 to 64 = faceted.
//
//   Torus
//   {
//       ringRadius = 0.65
//       tubeRadius = 0.35
//       verticalRadius = 1
//       holeDepth = 0.7
//       steps = 0
//   }
//       A true torus is impossible in KSP: every point of a planet's surface lies on a straight line
//       out from its center, so each direction can have only one surface point, and a hole straight
//       through the middle (or a ring that curls over itself) cannot be built. The closest thing is
//       the outside of a real torus with the hole turned into a crater: a sloping wall from the
//       ring's inner edge down to a flat floor in the middle, so you get a donut with a pit in it.
//       ringRadius       distance from the center to the middle of the ring's tube.
//       tubeRadius       radius of the tube. At most 98% of ringRadius.
//       verticalRadius   height of the tube compared with its width. 1 = round, 0.6 = a flat ring.
//       holeDepth        how deep the crater goes. 0 = filled in flush with the ring, 1 = almost down
//                        to the center of the body.
//       steps            straight sections around the ring. 0 = smooth, 3 to 64 = that many sections.
//
//   Capsule
//   {
//       verticalRadius = 2
//       steps = 0
//   }
//       verticalRadius   half the length from tip to tip, as a multiple of the width. 1 = a sphere,
//                        2 = twice as long as it is wide. Minimum 1.
//       steps            sides around the capsule. 0 = smooth, 3 to 64 = faceted.
//
//   Cross
//   {
//       verticalRadius = 1
//       armWidth = 0.3
//       steps = 4
//   }
//       Three bars crossing at the center, like a 3D plus sign.
//       verticalRadius   length of the up and down arms compared with the four side arms (which are 1).
//       armWidth         half the thickness of every arm, relative to the side arm length.
//       steps            sides of each arm's cross-section. 4 = square arms, 0 = round arms.
//
//   Fit: Circumradius (default) makes the farthest point of the shape touch the body radius, so the
//   shape always fits inside the sphere. Inradius makes the nearest point touch it instead; on a
//   hemisphere, torus or cross that nearest point is close to the center, so the shape would become
//   huge. Inradius suits a Capsule, or a Cylinder with verticalRadius of 1 or more, if you want
//   the walls to sit at the body radius.
//
//   Values outside their range are brought back into range, and a line is written to KSP.log
//   (search for "PolyhedronPQS").
//
// ---- Rounding the edges --------------------------------------------------------------------
//   smoothing  0 = sharp edges (default). Up to 0.5 (about a sphere).
//              0.03 barely softens the corners, 0.1 is clearly rounded, 0.25 is very round.
//              "fit" is applied after smoothing, so Circumradius still means the highest point
//              of the rounded body touches the radius.
//              Presets: rounds the rim of a cylinder, the base edge of a hemisphere, the corners
//              of a cross and the edges of a "steps" shape. A round capsule is already smooth.
//              On a torus it softens the creases around the crater.
//
// ---- Gravity -------------------------------------------------------------------------------
//   surfaceGravity     false by default. true = gravity points along the surface (into the face)
//                      instead of toward the center, and has the same strength everywhere on the
//                      surface. With normal gravity a cube pulls 3x harder at a face center than at
//                      a corner (the corner is 3x farther away) and pulls sideways near the edges.
//   gravitySmoothing   how gradually gravity turns across an edge. 0 = abrupt. Default 0.1.
//                      Width of the turn on a cube, seen from the center:
//                        0.03 ~7 deg   0.05 ~12 deg   0.1 ~25 deg   0.15 ~38 deg   0.25 ~61 deg
//                      Set it equal to "smoothing" and gravity matches the rounded surface exactly
//                      (nothing slides). Higher than "smoothing" makes edges feel like gentle hills.
//   gravityFadeHeight  height above the surface, as a fraction of the surface radius, over which
//                      surface gravity fades back into the normal pull toward the center. Default 0.25.
//                      Inside the body's nominal radius that pull is held at the body's normal surface
//                      gravity, so a low spot (the flat side of a hemisphere, the floor of a crater)
//                      does not turn crushing a few kilometers up. Outside the nominal radius it is
//                      exactly the stock gravity.
//   surfaceGravityScale  multiplier on the surface gravity strength. Default 1 (the body's normal
//                      surface gravity for its radius).
//   alignCamera        true by default (only matters with surfaceGravity). The free camera's "up"
//                      follows the gravity direction so the ground doesn't look tilted at edges.
//
// The mod is additive, so heightmaps and noise placed after it (higher "order") stack on top.

Kopernicus
{
    Body
    {
        name = MyCubeWorld
        // ... Properties, Orbit, etc. ...

        PQS
        {
            // ... Materials, Mods before this one ...

            Mods
            {
                VertexHeightPolyhedron
                {
                    order = 20
                    faces = 6
                    layout = Auto
                    fit = Circumradius
                    rotationX = 0
                    rotationY = 0
                    rotationZ = 0

                    smoothing = 0.1

                    surfaceGravity = true
                    gravitySmoothing = 0.1
                    gravityFadeHeight = 0.25
                    surfaceGravityScale = 1
                    alignCamera = true
                }
            }
        }
    }
}

// Irregular shapes. Each of these goes inside the same PQS > Mods node:
//
//   // a round-ish drum, 24 sides, a bit taller than it is wide, with softened edges
//   VertexHeightPolyhedron
//   {
//       order = 20
//       GeometricPreset = Cylinder
//       smoothing = 0.06
//       Cylinder
//       {
//           verticalRadius = 1.4
//           steps = 24
//       }
//   }
//
//   // a dome sitting on a flat base
//   VertexHeightPolyhedron
//   {
//       order = 20
//       GeometricPreset = Hemisphere
//       surfaceGravity = true
//       Hemisphere
//       {
//           verticalRadius = 1
//           baseDepth = 0.1
//       }
//   }
//
//   // a ring world with a deep crater in the middle
//   VertexHeightPolyhedron
//   {
//       order = 20
//       GeometricPreset = Torus
//       smoothing = 0.05
//       surfaceGravity = true
//       Torus
//       {
//           ringRadius = 0.7
//           tubeRadius = 0.3
//           holeDepth = 0.8
//       }
//   }
//
//   // a pill lying on its side (rotated 90 degrees)
//   VertexHeightPolyhedron
//   {
//       order = 20
//       GeometricPreset = Capsule
//       rotationX = 90
//       Capsule
//       {
//           verticalRadius = 2.5
//       }
//   }
//
//   // a jack with long up and down arms and round arms
//   VertexHeightPolyhedron
//   {
//       order = 20
//       GeometricPreset = Cross
//       smoothing = 0.08
//       Cross
//       {
//           verticalRadius = 1.4
//           armWidth = 0.25
//           steps = 0
//       }
//   }
//
// Adding it to an existing body with Module Manager:
//
// @Kopernicus:FOR[MyPack]
// {
//     @Body[MyExistingBody]
//     {
//         @PQS
//         {
//             @Mods
//             {
//                 VertexHeightPolyhedron
//                 {
//                     order = 20
//                     faces = 12
//                     smoothing = 0.08
//                     surfaceGravity = true
//                 }
//             }
//         }
//     }
// }
