feat: a galaxy keeps a retinue of satellites

- satellites are children inside the primary's own cube
- count and size drawn from the galaxy type's own band
- galaxyContainingSector answers which galaxy a point is in
- the seat margin is the whole retinue's reach
- a nucleus contrast scales to its own galaxy's population

Author: StannisMod

src/main/java/zmaster587/advancedRocketry/universe/ClusterField.java

@@ -72,18 +72,45 @@ public Optional<StarCluster> nucleusOf(long seed, Galaxy galaxy) {
         if (galaxy == null) {
             return Optional.empty();
         }
-        double u = CellHash.norm(CellHash.of(seed, galaxy.cellX(), galaxy.cellY(), galaxy.cellZ(),
-                SALT_NUCLEUS_RADIUS));
+        // Keyed on the galaxy's own CENTRE, not on its lattice index: a cube holds a primary and its
+        // satellites, and they share that index — so keying on it would give every galaxy in a group the
+        // same nucleus, and a satellite's core would be sized by its primary's draw.
+        double u = CellHash.norm(CellHash.of(seed, galaxy.centre().sectorX(),
+                galaxy.centre().sectorY(), galaxy.centre().sectorZ(), SALT_NUCLEUS_RADIUS));
         GalaxyGenConfig.ClusterType type = GalaxyGenConfig.NUCLEUS;
         double radiusLy = type.minRadiusLy + u * (type.maxRadiusLy - type.minRadiusLy);
         long s = config.minSpacing;
-        return Optional.of(new StarCluster(type,
+        return Optional.of(new StarCluster(type, nucleusSubdivisionFor(galaxy),
                 Math.floorDiv(galaxy.centre().sectorX(), s),
                 Math.floorDiv(galaxy.centre().sectorY(), s),
                 Math.floorDiv(galaxy.centre().sectorZ(), s),
                 superCellsForLightYears(radiusLy, config.minSpacing)));
     }
 
+    /**
+     * How finely a galaxy's NUCLEUS divides the lattice &mdash; scaled to the galaxy it is the centre of,
+     * never taken flat from the table.
+     *
+     * <p>Every other cluster's contrast is measured against the FIELD, whose density is real and the same
+     * everywhere; a nucleus's is a statement about its own galaxy's POPULATION, so it cannot be one
+     * number. The table's {@code k} is the real figure for a reference-sized galaxy (10⁷&times; the field
+     * at 10¹¹ stars), and a galaxy's population goes as its radius cubed, so {@code k} goes as the
+     * radius: {@code k = k_ref &middot; R / R_ref}. That holds the nucleus at a constant FRACTION of
+     * whatever it is the centre of.</p>
+     *
+     * <p>Measured, and the reason this is derived at all: the flat {@code k = 215} put ~4&middot;10⁷ stars
+     * inside a 6-light-year core of a 921-light-year dwarf that holds ~10⁷ altogether &mdash; a nucleus
+     * four times its own galaxy. It is the same error the table's {@code k} was once held down to avoid,
+     * one level lower, and it became reachable the moment satellite galaxies made small galaxies common.
+     * A dwarf's nucleus comes out at {@code k = 4}, i.e. barely a concentration, which is what a real
+     * dwarf spheroidal has.</p>
+     */
+    private static int nucleusSubdivisionFor(Galaxy galaxy) {
+        double scaled = GalaxyGenConfig.NUCLEUS.subdivision
+                * galaxy.radiusLy() / UniverseScale.REFERENCE_GALAXY_RADIUS_LY;
+        return (int) Math.max(1L, Math.min(GalaxyGenConfig.NUCLEUS.subdivision, Math.round(scaled)));
+    }
+
     /**
      * The cluster seated in cluster cell {@code (cx, cy, cz)}, or empty.
      *
@@ -118,7 +145,9 @@ public Optional<StarCluster> clusterAtIndex(long seed, Galaxy galaxy, long cx, l
         long ox = margin + Math.floorMod(CellHash.of(seed, cx, cy, cz, SALT_CLUSTER_OX), band);
         long oy = margin + Math.floorMod(CellHash.of(seed, cx, cy, cz, SALT_CLUSTER_OY), band);
         long oz = margin + Math.floorMod(CellHash.of(seed, cx, cy, cz, SALT_CLUSTER_OZ), band);
-        return Optional.of(new StarCluster(type, cx * spacingSuperCells + ox,
+        // The type's own k: an open cluster's and a globular's contrast is measured against the FIELD,
+        // whose density is real and uniform, so it needs no scaling to the galaxy it sits in.
+        return Optional.of(new StarCluster(type, type.subdivision, cx * spacingSuperCells + ox,
                 cy * spacingSuperCells + oy, cz * spacingSuperCells + oz, radius));
     }
 

src/main/java/zmaster587/advancedRocketry/universe/ClusteredGalaxyGenerator.java

@@ -642,7 +642,8 @@ public List<Nebula> nebulaeAround(long seed, GalacticCoord cell, double radiusLy
             return Collections.emptyList();
         }
         GalacticCoord c = cell.cellCentre();
-        Optional<Galaxy> galaxy = galaxies.galaxyOwningSector(seed, c.sectorX(), c.sectorY(),
+        // The galaxy the observer is INSIDE, so a cell in a satellite sees the satellite's clouds.
+        Optional<Galaxy> galaxy = galaxies.galaxyContainingSector(seed, c.sectorX(), c.sectorY(),
                 c.sectorZ());
         if (!galaxy.isPresent()) {
             return Collections.emptyList();
@@ -669,7 +670,7 @@ public double columnDensityBetween(long seed, GalacticCoord from, GalacticCoord
             return 0d;
         }
         GalacticCoord a = from.cellCentre();
-        Optional<Galaxy> galaxy = galaxies.galaxyOwningSector(seed, a.sectorX(), a.sectorY(),
+        Optional<Galaxy> galaxy = galaxies.galaxyContainingSector(seed, a.sectorX(), a.sectorY(),
                 a.sectorZ());
         return galaxy.isPresent() ? nebulae.columnDensityBetween(seed, galaxy.get(), from, to) : 0d;
     }
@@ -844,7 +845,9 @@ long minEdge() {
      */
     private int subdivisionAt(long seed, long supX, long supY, long supZ) {
         long s = config.minSpacing;
-        Optional<Galaxy> galaxy = galaxies.galaxyOwningSector(seed, supX * s + s / 2L,
+        // The CONTAINING galaxy: a cluster inside a satellite belongs to the satellite, and its nucleus
+        // sits at the satellite's own centre.
+        Optional<Galaxy> galaxy = galaxies.galaxyContainingSector(seed, supX * s + s / 2L,
                 supY * s + s / 2L, supZ * s + s / 2L);
         if (!galaxy.isPresent()) {
             return 1;
@@ -894,14 +897,19 @@ private static long subIndex(long offsetInCoarse, long coarseEdge, int k) {
     }
 
     /**
-     * How dense the owning galaxy is at this sector triple, in {@code [0, 1]} — zero in the void and
-     * zero past a galaxy's declared edge.
+     * How dense the CONTAINING galaxy is at this sector triple, in {@code [0, 1]} — zero in the void and
+     * zero past every galaxy's declared edge.
      *
      * <p>The galaxy cell is a coarse reading of the sector, so this is O(1) and needs no stored index:
-     * every point belongs to exactly one galaxy cell, and that cell either holds a galaxy or is void.</p>
+     * every point belongs to exactly one galaxy cell, and that cell holds a primary galaxy, its
+     * satellites, or nothing.</p>
+     *
+     * <p><b>The containing galaxy, not the cube's owner.</b> A cube holds a primary and its retinue, so
+     * reading the owner's profile at a point inside a satellite would answer zero — and the satellites
+     * would be named, addressable and completely empty of stars.</p>
      */
     private double galaxyProfileAt(long seed, long sectorX, long sectorY, long sectorZ) {
-        Optional<Galaxy> galaxy = galaxies.galaxyOwningSector(seed, sectorX, sectorY, sectorZ);
+        Optional<Galaxy> galaxy = galaxies.galaxyContainingSector(seed, sectorX, sectorY, sectorZ);
         if (!galaxy.isPresent()) {
             return 0d;
         }

src/main/java/zmaster587/advancedRocketry/universe/Galaxy.java

@@ -56,6 +56,7 @@ public final class Galaxy {
     private final long cellX;
     private final long cellY;
     private final long cellZ;
+    private final int satelliteIndex;
     private final GalacticCoord centre;
     private final LightYearVector seat;
     private final LightYearVector peculiarVelocity;
@@ -79,21 +80,27 @@ public final class Galaxy {
 
     /**
      * @param cellX      the galaxy-lattice index this galaxy is seated in
+     * @param satelliteIndex {@code 0} for the cube's PRIMARY galaxy, {@code 1..n} for a satellite of
+     *                   it. A cube holds one primary and its retinue, so the lattice index alone no
+     *                   longer identifies a galaxy — this is what distinguishes them, in the name and
+     *                   in every draw made per galaxy rather than per cell
      * @param centre     its centre, as a cell name
      * @param radiusLy   its declared radius in light years — drawn inside {@code type}'s band
      * @param tilt       the angle its pole makes with the static +Y axis, in radians
      * @param node       the direction that pole leans in, in radians about +Y
      * @param armPitch   the arms' pitch angle in radians (ignored when the type has no arms)
      * @param armPhase   where arm zero starts, in radians
      * @param peculiarVelocity its comoving velocity in light years per tick — its own motion through
-     *                   the expanding universe, on top of the expansion
+     *                   the expanding universe, on top of the expansion. A satellite carries its
+     *                   PRIMARY's, so a group travels together
      */
-    public Galaxy(long cellX, long cellY, long cellZ, GalacticCoord centre,
+    public Galaxy(long cellX, long cellY, long cellZ, int satelliteIndex, GalacticCoord centre,
                   GalaxyGenConfig.GalaxyType type, double radiusLy, double tilt, double node,
                   double armPitch, double armPhase, LightYearVector peculiarVelocity) {
         this.cellX = cellX;
         this.cellY = cellY;
         this.cellZ = cellZ;
+        this.satelliteIndex = Math.max(0, satelliteIndex);
         this.centre = centre;
         this.seat = LightYearVector.ofCell(centre);
         this.peculiarVelocity = (peculiarVelocity == null) ? LightYearVector.ZERO : peculiarVelocity;
@@ -186,9 +193,29 @@ public double armPhase() {
         return armPhase;
     }
 
-    /** This galaxy's designation — procedurally-generated galaxy, named for the cell it is seated in. */
+    /**
+     * {@code 0} for the cube's primary galaxy, {@code 1..n} for one of its satellites. A cube holds a
+     * primary AND its retinue, so this is the second half of a galaxy's identity.
+     */
+    public int satelliteIndex() {
+        return satelliteIndex;
+    }
+
+    /** Whether this galaxy is a satellite of the primary seated in the same cube. */
+    public boolean isSatellite() {
+        return satelliteIndex > 0;
+    }
+
+    /**
+     * This galaxy's designation — procedurally-generated galaxy, named for the cell it is seated in,
+     * and for its place in that cube's retinue when it is not the primary.
+     *
+     * <p>The suffix is not decoration: a satellite is a destination with an address, and two galaxies in
+     * one cube sharing a name would be two places a player could neither tell apart nor write down.</p>
+     */
     public String name() {
-        return "PGG-" + cellX + "." + cellY + "." + cellZ;
+        String cell = "PGG-" + cellX + "." + cellY + "." + cellZ;
+        return isSatellite() ? cell + "-S" + satelliteIndex : cell;
     }
 
     // ─── Membership and profile ────────────────────────────────────────────────