final comment sweep: section separators, signature-only javadocs and history notes removed, stale comments corrected (sign/contents model lookup, inverted entity cubes, item-bounds use, datapack folder search, biome tint argb, water-only overlay faces, beacon first section, mushroom-cow instanceof example, legacy skin arm copy, elytra and pack-detection notes in the scripts, pptest scene descriptions), comments only

tools/edgecase-plugin/pptest/PPTest.java

@@ -105,8 +105,8 @@ public class PPTest extends JavaPlugin {
         scene("chests_e", this::chests, 16, 5, 3, 4.5, 0, 3);
         scene("chests_w", this::chests, -7, 5, 3, 4.5, 0, 3);
         scene("translucent", this::translucent, 4.5, 2.8, -5.5, 4.5, 0.8, 2);
-        // Projectile orientation (vanilla ArrowRenderer/ThrownTridentRenderer): flying stars around gold pillars
-        // (tips point radially outward, rings level / +35 deg / -35 deg) and arrows/tridents stuck in stone pillars.
+        // Projectile orientation (vanilla ArrowRenderer/ThrownTridentRenderer): hovering stars of arrows (gold pillar)
+        // and tridents (diamond pillar), tips radially outward, rings level / +35 / -35 deg; arrows/tridents stuck in stone.
         scene("proj_fly_top", this::projFly, 6.5, 13, 2.2, 6.5, 0, 2);
         scene("proj_fly_side", this::projFly, 6.5, 2.6, -8, 6.5, 2.4, 2);
         scene("proj_fly_obl", this::projFly, -2, 6, -6, 6.5, 2, 2);
@@ -131,7 +131,7 @@ public class PPTest extends JavaPlugin {
         scene("layers_top", this::layers, 5.5, 6, 2.0, 5.5, 0, 2.5);
         scene("layers_wither", this::withers, 3.5, 4, -9, 3.5, 2.2, 1);
         scene("layers_wither_close", this::withers, 6, 3.4, -3.5, 6, 2.6, 1);
-        // Block entities (vanilla BlockEntityRenderer poses): signs, banners, heads in all 16 rotations + wall
+        // Block entities (vanilla BlockEntityRenderer poses): signs and banners in all 16 rotations, heads in 5, wall
         // mounts, and bells/pots/shulker boxes/lecterns/conduits, each layout seen from two sides.
         scene("be_signs_s", this::beSigns, 7, 3, 8, 7, 0.5, 1);
         scene("be_signs_n", this::beSigns, 7, 1.3, -8, 7, 0.6, 1);
@@ -237,7 +237,7 @@ public class PPTest extends JavaPlugin {
         scene("be_contents_close", this::beContents, 1.2, 1.8, 2.2, 1.5, 0.6, 0);
         scene("be_contents_beam", this::beContents, 4, 6, 26, 10, 9, 6);
         scene("be_contents_portal", this::beContents, 11.5, 3.6, -1.8, 11.5, 0, 1.2);
-        // Items in detail (decompiled 26.3 special renderers): shields (plain, base colour, banner patterns), chests,
+        // Items in detail (vanilla special renderers): shields (plain, base colour, banner patterns), chests,
         // spawner/vault held by armor stands (+ a baby zombie: baby hand offset), item displays (fixed), item frames
         // (rotation 0/1) and dropped (ground: lift = 0.1625 - model min y). items_inverted: spawner, trial spawner and
         // vault as block, block display, item display and dropped item (inverted inner faces). xmas_chests: chests,
@@ -465,7 +465,7 @@ public class PPTest extends JavaPlugin {
             ts.update(true, false);
             put(o, 4, 0, 6, "trial_spawner[trial_spawner_state=waiting_for_players]");
         }
-        // Beacon on a 3x3 iron pyramid, red glass 2 above, blue glass 4 above (red+blue = averaged section).
+        // Beacon on a 3x3 iron pyramid, red glass 2 above, blue glass pane 4 above (red+blue = averaged section).
         for (int x = -1; x <= 1; x++) for (int z = -1; z <= 1; z++) put(o, 10 + x, -1, 6 + z, "iron_block");
         put(o, 10, 0, 6, "beacon");
         put(o, 10, 2, 6, "red_stained_glass");
@@ -642,10 +642,9 @@ public class PPTest extends JavaPlugin {
         }
     }
 
-    // --- poses ------------------------------------------------------------------------------------
-
     private void posePets(Location o) {
-        // Row 1 (z=0): foxes — standing, sitting, sleeping, crouching, crouching+leaping, faceplanted.
+        // Row 1 (z=0): foxes — standing, sitting, sleeping, crouching, crouching+leaping, faceplanted, baby
+        // sleeping/sitting.
         Fox f0 = rfSpawn(o, 0, 0, 0, 180, Fox.class);
         hands(f0, Material.SWEET_BERRIES, null);
         Fox f1 = rfSpawn(o, 1.2, 0, 0, 180, Fox.class);
@@ -866,8 +865,8 @@ public class PPTest extends JavaPlugin {
 
     /**
      * Loads the scene's chunks and waits until they are entity-ticking before building: entities spawned into a
-     * chunk that only becomes entity-ticking a few (variable) ticks later start moving late (projectile scenes were
-     * not reproducible).
+     * chunk that only becomes entity-ticking a few (variable) ticks later start moving late (non-reproducible
+     * projectile scenes).
      */
     private void run(Scene sc, Location o) {
         loadArea(o);
@@ -911,7 +910,7 @@ public class PPTest extends JavaPlugin {
 
     private static final List<String> LARGE = List.of("proj_", "rf_", "pose_", "frames", "geo_", "liq_", "items_", "xmas_");
 
-    /** *_sq scenes square, newer scene families 960x640, the rest 480x320. */
+    /** *_sq scenes 384x384, the LARGE families 960x640, the rest 480x320. */
     private static Resolution resolution(String name) {
         if (name.endsWith("_sq")) return new Resolution(384, 384);
         return LARGE.stream().anyMatch(name::startsWith) ? new Resolution(960, 640) : new Resolution(480, 320);
@@ -1013,8 +1012,7 @@ public class PPTest extends JavaPlugin {
 
     /** Clears the area (blocks + entities) and lays a 24x24 stone floor at the origin's y-1. */
     private void prepareArea(Location o) {
-        // Blocks first: removing a campfire/shelf/container drops its items, which the entity sweep then removes
-        // (before, the previous run's cooked campfire food lay around at random).
+        // Blocks first: removing a campfire/shelf/container drops its items, which the entity sweep then removes.
         for (int x = -6; x < 18; x++)
             for (int z = -12; z < 12; z++)
                 for (int y = -1; y < 12; y++)
@@ -1023,8 +1021,6 @@ public class PPTest extends JavaPlugin {
         for (Entity e : w.getNearbyEntities(o.clone().add(6, 5, 2), 20, 20, 20)) if (!(e instanceof Player)) e.remove();
     }
 
-    // --- helpers ---------------------------------------------------------------------------------
-
     /** {@link #rfSpawn} with the body turned to {@code yaw} (spawned mobs otherwise keep a random body yaw). */
     private <T extends Entity> T spawn(Location o, double x, double y, double z, float yaw, Class<T> type) {
         T e = rfSpawn(o, x, y, z, yaw, type);
@@ -1075,8 +1071,6 @@ public class PPTest extends JavaPlugin {
         if (off != null) le.getEquipment().setItemInOffHand(it(off));
     }
 
-    // --- scenes ----------------------------------------------------------------------------------
-
     private void held(Location o) {
         hands(spawn(o, 0, 0, 0, 180, Zombie.class), Material.IRON_SWORD, Material.SHIELD);
         hands(spawn(o, 1.6, 0, 0, 180, Skeleton.class), Material.BOW, null);
@@ -1196,7 +1190,7 @@ public class PPTest extends JavaPlugin {
         i3.setItemStack(it(Material.PLAYER_HEAD));
         ItemDisplay i4 = spawn(o, 2, 0.5, 2.5, 0, ItemDisplay.class);
         i4.setItemStack(it(Material.SHIELD));
-        // Block displays: rotated stairs, scaled chest (block entity!), banner, bed, glass.
+        // Block displays: rotated + scaled stairs, chest (block entity), banner, glass, sign.
         BlockDisplay b1 = spawn(o, 3.5, 0, 2.5, 0, BlockDisplay.class);
         b1.setBlock(Bukkit.createBlockData("minecraft:oak_stairs[facing=east]"));
         b1.setTransformation(new Transformation(new Vector3f(), new Quaternionf().rotateY(0.6f), new Vector3f(0.8f), new Quaternionf()));
@@ -1296,7 +1290,7 @@ public class PPTest extends JavaPlugin {
                 put(o, STEP[i][0], 1 + age, STEP[i][1], "shelf_mushroom[age=" + age + ",facing=" + DIRS[i] + "]");
     }
 
-    /** Blockstate y-rotations: ladders, stairs, wall torches, furnaces, logs on all sides of stone pillars. */
+    /** Blockstate y-rotations: ladders, wall torches, stairs, furnaces on all sides of stone pillars; fence, door, logs. */
     private void rotated(Location o) {
         String[] kinds = {"ladder[facing=%s]", "wall_torch[facing=%s]", "oak_stairs[facing=%s]", "furnace[facing=%s]"};
         for (int k = 0; k < kinds.length; k++) {
@@ -1440,8 +1434,6 @@ public class PPTest extends JavaPlugin {
         t.setBillboard(Display.Billboard.CENTER);
     }
 
-    // --- conditional layers ----------------------------------------------------------------------
-
     private void layers(Location o) {
         tame(spawn(o, 0, 0, 0, 180, Cat.class), DyeColor.RED);
         tame(spawn(o, 1.2, 0, 0, 180, Cat.class), DyeColor.BLUE);
@@ -1476,8 +1468,6 @@ public class PPTest extends JavaPlugin {
         half.setHealth(half.getAttribute(Attribute.MAX_HEALTH).getValue() / 2 - 1);
     }
 
-    // --- data-driven variants / pose flags / armor wearers ------------------------------------------
-
     private static <T extends Keyed> List<T> registry(RegistryKey<T> key) {
         List<T> out = new ArrayList<>();
         RegistryAccess.registryAccess().getRegistry(key).forEach(out::add);
@@ -1682,8 +1672,6 @@ public class PPTest extends JavaPlugin {
         faceNorth(o);
     }
 
-    // --- projectiles -----------------------------------------------------------------------------
-
     /** Spawns a projectile at p moving along dir, rotated like vanilla Projectile#shoot (yaw atan2(x,z), pitch up). */
     private Projectile projectile(Location p, Vector dir, double speed, boolean gravity, Class<? extends Projectile> type) {
         Vector d = dir.clone().normalize();
@@ -1741,7 +1729,7 @@ public class PPTest extends JavaPlugin {
                 Vector n = dir(out, 0);
                 Vector t = new Vector(n.getZ(), 0, -n.getX());
                 double dist = 1.5 + 3.5;
-                // rising from low, level but 20 deg sideways, falling from high
+                // Rising from low, level but 20 deg sideways, falling from high.
                 double[][] shots = {{-1, 0.6, 25, 0}, {0, 1.6, 0, 20}, {1, 3.4, -25, 0}};
                 for (double[] sh : shots) {
                     Location p = o.clone().add(cx + n.getX() * dist + t.getX() * sh[0], sh[1], cz + n.getZ() * dist + t.getZ() * sh[0]);
@@ -1749,7 +1737,7 @@ public class PPTest extends JavaPlugin {
                     if (trident) projectile(p, d, 2.0, true, Trident.class);
                     else projectile(p, d, 1.5, true, (Class<? extends AbstractArrow>) (side % 2 == 0 ? Arrow.class : SpectralArrow.class));
                 }
-                // steep shot into the floor, diagonally away from the pillar
+                // Steep shot into the floor, diagonally away from the pillar.
                 Vector diag = dir(out + 45, 0);
                 Location p = o.clone().add(cx + diag.getX() * 2.6, 3, cz + diag.getZ() * 2.6);
                 Vector d = dir(out + 45, trident ? -70 : -60);
@@ -1759,8 +1747,6 @@ public class PPTest extends JavaPlugin {
         }
     }
 
-    // --- block-entity scenes ------------------------------------------------------------------------
-
     private void put(Location o, int x, int y, int z, String data) {
         o.clone().add(x, y, z).getBlock().setBlockData(Bukkit.createBlockData("minecraft:" + data), false);
     }
@@ -1877,8 +1863,6 @@ public class PPTest extends JavaPlugin {
         }
     }
 
-    // --- item frames -------------------------------------------------------------------------------
-
     private void frames(Location o) {
         for (int x = -2; x <= 11; x++)
             for (int y = 0; y <= 5; y++) put(o, x, y, 4, "stone");
@@ -1942,7 +1926,7 @@ public class PPTest extends JavaPlugin {
         frame(o, 5, 5, 5, BlockFace.NORTH, false, synthMap(), 0, true);
     }
 
-    /** Rows of cross/rescaled plants on grass (z=0..3), potted plants and stems; see the geo_* scenes. */
+    /** Rows of cross/rescaled plants on grass (z=0..3), potted plants and stems. */
     private void geoPlants(Location o) {
         for (int x = -1; x <= 12; x++) for (int z = -1; z <= 5; z++) put(o, x, -1, z, "grass_block");
         String[] row0 = {"short_grass", "fern", "dandelion", "poppy", "azure_bluet", "oxeye_daisy", "cornflower",
@@ -2130,8 +2114,6 @@ public class PPTest extends JavaPlugin {
         return mapItem(v);
     }
 
-    // --- fluids ------------------------------------------------------------------------------------------------
-
     /** Sets the biome of the scene area (deterministic water colour / water fog). */
     private void biome(Location o, Biome biome) {
         for (int x = -8; x < 20; x += 2)