POLYTRIUS - PARALLAX SCATTERS
=============================

REQUIREMENTS
  - Kopernicus
  - Parallax Continued, INCLUDING the "Parallax_StockScatterTextures" folder from its download
    (the rocks, shrub and oak tree here are borrowed from it)

FOLDER LAYOUT (everything lives inside your existing pack folder)

GameData/
  000_Polytrius/
    Polytrius.cfg                       <- REPLACE yours with the updated one (3 changes, see below)
    Parallax/
      PolytriusScatters.cfg             <- the scatter config
      README_Parallax.txt
      Models/                           <- YOUR custom .mu models go here (NOT in PluginData)
        Trees/
        Bushes/
        Rocks/
    PluginData/
      Polytrius/
        PolytriusBiomes.png             <- new biome map (new)
        PolytriusColor.dds  ...         <- your existing textures, unchanged
        Scatters/                       <- YOUR custom scatter textures (.dds) go here
          Trees/
          Bushes/
          Rocks/

  Why the split: KSP only loads .mu models that are OUTSIDE PluginData, so models go in
  000_Polytrius/Parallax/Models. Parallax loads its textures itself, and keeping .dds files
  INSIDE PluginData stops KSP from loading them a second time (wasted RAM).

CHANGES MADE TO Polytrius.cfg
  1. Properties: added biomeMap + 5 Biomes (Ocean, Shores, Lowlands, Highlands, Peaks).
     This replaces the Ike biomes Polytrius was inheriting from its template.
  2. PQS: maxLevel 6 -> 14 (6 gave ~17 km terrain triangles on a 9,750 km world).
  3. PQS Mods: added the "Parallax" PQSMod (Parallax requires it on every scatter body).

HOW OCEANS ARE KEPT CLEAR
  - Every scatter has minAltitude > 0. Parallax measures altitude from sea level, and the
    green on your colour map is exactly the below-sea-level terrain, so nothing spawns there.
  - Every scatter also blacklists the "Ocean" biome. Everything except pebbles also
    blacklists "Shores" (0-150 m), and trees also skip "Peaks" (> 8000 m).

SCATTERS
  Pebbles     tiny rock clusters, coloured by the ground beneath them    range 60 m
  SmallRocks  Duna-style rocks, crimson tint                             range 120 m
  MedRocks    clumped rocky patches                                      range 400 m
  BouldersA/B sparse, large (1-2.4x scale), grouped, collidable          range 3 km
  Bushes      stock Kerbin shrub, 160-9500 m                             range 300 m
  OakTree     stock Kerbin oak (+ OakTreeTop canopy), 200-7500 m         range 10.5 km

TUNING
  In flight on Polytrius press ALT+P (Parallax GUI) -> Scatters, pick one and change values
  live (population, scale, colour, ranges). Use the GUI's save/export button and copy the
  values back into PolytriusScatters.cfg.
  - Rock colour:   _Color in each Material (R,G,B multipliers; >1 brightens)
  - Density:       populationMultiplier (objects per terrain triangle) and spawnChance
  - Clumping:      DistributionNoise frequency / noiseType / cutoffScale
  - If you change PQS maxLevel, density changes: each +1 level = about 1/4 the objects.


USING YOUR OWN TREE (or bush / rock)
====================================

1. MODEL (Blender -> Unity -> .mu)
   - Make 3 meshes per object: LOD0 (full detail), LOD1 (~30-50% tris), LOD2 (very low, or
     a camera-facing billboard quad for trees).
   - Origin at the BASE of the trunk (the point that sits on the ground), Y up.
   - One mesh, one material per model. Parallax reads the MeshFilter on the ROOT object of the
     .mu, so the mesh must be on the root GameObject, not on a child.
   - Real-world scale in metres (1 unit = 1 m); minScale/maxScale then multiply it.
   - Trees: you can make the trunk and the leaves two separate models. The trunk becomes a
     Scatter, the leaves a SharedScatter with parentName = <trunk scatter name>, exactly like
     OakTree / OakTreeTop. The leaves model must share the trunk's origin.
   - Export each mesh as .mu with KSP PartTools in Unity 2019.4 (the KSP 1.12 Unity version).
     Put the mesh on the root of an empty-scene object, add a PartTools component, write .mu.
     (Blender add-ons that export .mu directly, e.g. "io_object_mu", also work.)
   - Save as e.g.
       GameData/000_Polytrius/Parallax/Models/Trees/myTreeLOD0.mu
       GameData/000_Polytrius/Parallax/Models/Trees/myTreeLOD1.mu
       GameData/000_Polytrius/Parallax/Models/Trees/myTreeLOD2.mu

2. TEXTURES
   - Colour: DXT5 .dds (DXT1 if no transparency). Alpha = cutout for leaves.
   - Normal map: .dds, standard tangent-space normal (DXT5 is fine).
   - Optional for leaves: thickness map (_ThicknessMap) for subsurface glow.
   - Generate mipmaps. Export with "flip vertically" ticked if your tool asks (DDS for Unity).
   - Save as e.g.
       GameData/000_Polytrius/PluginData/Polytrius/Scatters/Trees/myTree.dds
       GameData/000_Polytrius/PluginData/Polytrius/Scatters/Trees/myTreeNrm.dds

3. CONFIG - edit the OakTree scatter (or copy it and rename):
       model = 000_Polytrius/Parallax/Models/Trees/myTreeLOD0      // no ".mu"!
       _MainTex = 000_Polytrius/PluginData/Polytrius/Scatters/Trees/myTree.dds
       _BumpMap = 000_Polytrius/PluginData/Polytrius/Scatters/Trees/myTreeNrm.dds
     and in LODs:
       LOD { model = 000_Polytrius/Parallax/Models/Trees/myTreeLOD1  range = 215 ... }
       LOD { model = 000_Polytrius/Parallax/Models/Trees/myTreeLOD2  range = 2450 ... }
   - Model paths have NO extension; texture paths DO (.dds).
   - Exactly two LOD nodes per scatter.
   - Leaves/cutouts need Keywords { name = ALPHA_CUTOFF } and _Cutoff = 0.5, and usually
     _CullMode = 0 (draw both sides). Swaying needs name = WIND plus the _Wind* values and
     _WindMap (keep the stock grassuv2.dds path).
   - Every scatter in a Body needs a unique name.

4. CHECK
   If a path is wrong, Parallax swaps in a pink error mesh and logs
   "This model file doesn't exist: ..." in KSP.log / Logs/Parallax/. Search the log for
   "[Parallax]" to see scatter and biome loading messages.


PLACEHOLDER FLORA (PolyTree / PolyBush)
=======================================
Ready-to-load .mu files are already in Parallax/Models/Trees and /Bushes, with placeholder
textures in PluginData/Polytrius/Scatters. The config uses them as PolyTree, PolyTreeLeaves
and PolyBush.

  Trees/polyTreeTrunkLOD0.mu   trunk + roots + horn branches + shelf mushrooms (~2200 tris)
  Trees/polyTreeTrunkLOD1.mu   same, lower poly (~800 tris)
  Trees/polyTreeBillboard.mu   LOD2 camera-facing quad (whole tree incl. leaves)
  Trees/polyTreeLeavesLOD0/1   sparse leaf cards (SharedScatter riding on the trunk)
  Bushes/polyBushLOD0/1/2      low spreading stems + leaf cards (same leaf texture)
  Trees/polyTreeTall*          variant: ~4.8 m tall, slimmer trunk, 5 longer branches
  Trees/polyTreeLanky*         variant: ~6 m tall, thin curved trunk, 4 long branches
  (each variant has TrunkLOD0/1, LeavesLOD0/1 and its own Billboard + polyTree*Billboard.dds)

  Size at scale 1: tree ~3.3 m tall x 5.4 m across the roots (trunk ~1.3 m thick);
  bush ~1.8 m wide x 0.45 m tall. Origin = ground contact, trunk extends 0.4 m below ground
  so it never floats on slopes.

UV LAYOUT (paint your real textures to this)
  polyTreeBark.dds   U 0-0.75        bark (trunk, roots, branches; tiles vertically)
                     U 0.75-1, V 0.5-1  mushroom shelf tops
                     U 0.75-1, V 0-0.5  mushroom undersides / gills
  polyLeaves.dds     U 0-0.875       one leaf cluster, alpha = cutout, stem at bottom centre
                     U 0.9-1.0       solid stem colour (bush stems)
  polyTreeBillboard  whole-tree picture seen from the side, alpha cutout
  *Nrm.dds           flat placeholder normal maps (replace with real ones)

EDITING IN BLENDER
  Option A: install taniwha's "io_object_mu" add-on, File > Import > KSP Mu, edit, then
            File > Export > KSP Mu over the same file name.
  Option B: import the OBJs from Polytrius_Flora_Blender_Source (Y-up, metres), edit, and
            export .mu with the add-on or PartTools.
  Keep: origin at the base, one mesh per file, mesh on the root object, no extra children.
  The billboard must stay a single quad in the XY plane, base at y = 0.
  If you re-export textures as DDS, flip vertically and generate mipmaps.


NOISE FREQUENCY ON POLYTRIUS (important if you add scatters)
  Parallax samples DistributionNoise on the unit sphere, so "frequency" means patches per planet
  radius, not per km. A value copied from a stock config makes patches (forests, rock fields)
  (Polytrius radius / stock body radius) times too big: x16 vs Kerbin, x30 vs Duna, x49 vs the Mun.
  Multiply copied frequencies by that ratio. Very high frequencies lose float precision in the
  top octaves, so use 2-4 octaves above ~20000.

TREE VARIANTS
  PolyTree, PolyTreeTall and PolyTreeLanky are three separate Scatter + SharedScatter pairs with
  different noise seeds, so they form their own groves that overlap. Mix ratio = their spawnChance
  (0.25 / 0.2 / 0.15). To add another variant: copy one pair, give both a new unique name, set the
  SharedScatter's parentName to the new Scatter name, change the model paths and the noise seed.
