Expand biome api

build-data/paper.at

@@ -537,8 +537,11 @@ public net.minecraft.world.level.Level thunderLevel
 public net.minecraft.world.level.NaturalSpawner SPAWNING_CATEGORIES
 public net.minecraft.world.level.StructureManager level
 public net.minecraft.world.level.biome.Biome climateSettings
+public net.minecraft.world.level.biome.Biome getHeightAdjustedTemperature(Lnet/minecraft/core/BlockPos;I)F
 public net.minecraft.world.level.biome.Biome getTemperature(Lnet/minecraft/core/BlockPos;I)F
 public net.minecraft.world.level.biome.Biome$ClimateSettings
+public net.minecraft.world.level.biome.MobSpawnSettings mobSpawnCosts
+public net.minecraft.world.level.biome.MobSpawnSettings spawners
 public net.minecraft.world.level.block.Block popExperience(Lnet/minecraft/server/level/ServerLevel;Lnet/minecraft/core/BlockPos;I)V
 public net.minecraft.world.level.block.ChestBlock isBlockedChestByBlock(Lnet/minecraft/world/level/BlockGetter;Lnet/minecraft/core/BlockPos;)Z
 public net.minecraft.world.level.block.ChiseledBookShelfBlock getHitSlot(Lnet/minecraft/world/phys/BlockHitResult;Lnet/minecraft/world/level/block/state/BlockState;)Ljava/util/OptionalInt;

paper-api/src/main/java/io/papermc/paper/world/biome/BiomeClimate.java

@@ -0,0 +1,35 @@
+package io.papermc.paper.world.biome;
+
+import org.bukkit.Location;
+
+public interface BiomeClimate {
+    /**
+     * Determines if the biome has precipitation.
+     *
+     * @return true if the biome has precipitation.
+     */
+    boolean hasPrecipitation();
+
+    /**
+     * Controls gameplay features like grass and foliage color,
+     * and a height adjusted temperature.
+     *
+     * @return the temperature of the biome.
+     */
+    float temperature();
+
+    /**
+     * Controls grass and foliage color.
+     *
+     * @return the downfall of the biome.
+     */
+    float downfall();
+
+    /**
+     * Modifies temperature before calculating the height adjusted temperature.
+     *
+     * @param location the position to adjust the temperature for.
+     * @return the adjusted temperature.
+     */
+    float adjustedTemperature(Location location);
+}

paper-api/src/main/java/io/papermc/paper/world/biome/BiomeMobSpawning.java

@@ -0,0 +1,85 @@
+package io.papermc.paper.world.biome;
+
+import org.bukkit.entity.EntityType;
+import org.bukkit.entity.SpawnCategory;
+import org.checkerframework.checker.index.qual.Positive;
+import java.util.List;
+import java.util.Map;
+
+public interface BiomeMobSpawning {
+
+    /**
+     * Spawn category to a list of spawner data objects, one for each
+     * mob which should spawn in this biome. If this object doesn't
+     * contain a certain category, mobs in this category do not spawn.
+     *
+     * @return The spawner data
+     */
+    Map<SpawnCategory, List<MobData>> spawners();
+
+    /**
+     * New mob's cost. Only mobs listed here use the spawn cost mechanism.
+     *
+     * @see <a href="https://minecraft.wiki/w/Mob_spawning">Mob spawning#Spawn costs</a>
+     * @return The map of entity type to cost
+     */
+    Map<EntityType, SpawnCost> entityCost();
+
+    /**
+     * The spawner data for a single mob.
+     */
+    interface MobData {
+
+        /**
+         * The entity type of the mob.
+         *
+         * @return The entity type
+         */
+        EntityType type();
+
+        /**
+         * The weight of the mob. Higher weights mean the mob is more likely to spawn.
+         *
+         * @return The weight
+         */
+        int weight();
+
+        /**
+         * The minimum count of mobs to spawn in a pack.
+         *
+         * @return The minimum count
+         */
+        @Positive
+        int minCount();
+
+        /**
+         * The maximum count of mobs to spawn in a pack.
+         *
+         * @return The maximum count
+         */
+        @Positive
+        int maxCount();
+    }
+
+    /**
+     * The spawn cost for a mob.
+     *
+     * @see <a href="https://minecraft.wiki/w/Mob_spawning">Mob spawning#Spawn costs</a>
+     */
+    interface SpawnCost {
+
+        /**
+         * The energy budget of the mob.
+         *
+         * @return The energy budget
+         */
+        double energyBudget();
+
+        /**
+         * The charge of the mob.
+         *
+         * @return The charge
+         */
+        double charge();
+    }
+}

paper-api/src/main/java/io/papermc/paper/world/biome/BiomeSpecialEffects.java

@@ -0,0 +1,106 @@
+package io.papermc.paper.world.biome;
+
+import io.papermc.paper.world.biome.effects.AdditionSound;
+import io.papermc.paper.world.biome.effects.MoodSound;
+import io.papermc.paper.world.biome.effects.MusicEntry;
+import org.bukkit.Color;
+import org.bukkit.Location;
+import org.bukkit.Sound;
+import java.util.List;
+import java.util.Optional;
+
+/**
+ * Ambient effects in this biome.
+ */
+public interface BiomeSpecialEffects {
+    /**
+     * The fog color.
+     *
+     * @return color to use for fog.
+     */
+    Color fogColor();
+
+    /**
+     * The water color.
+     *
+     * @return color to use for water blocks and cauldrons.
+     */
+    Color waterColor();
+
+    /**
+     * The water fog color.
+     *
+     * @return color to use for fog underwater.
+     */
+    Color waterFogColor();
+
+    /**
+     * The sky color.
+     *
+     * @return color to use for the sky.
+     */
+    Color skyColor();
+
+    /**
+     * The color to use for tree leaves and vines.
+     * If not present, the value depends on downfall and the temperature.
+     *
+     * @return foliage color.
+     */
+    Optional<Color> foliageColor();
+
+    /**
+     * The color to use for grass blocks, short grass,
+     * tall grass, ferns, tall ferns, and sugar cane.
+     * If not present, the value depends on downfall and the temperature.
+     *
+     * @return grass color.
+     */
+    Optional<Color> grassColor();
+
+    /**
+     * The biome ambient sound.
+     *
+     * @return the ambient sound.
+     */
+    Optional<Sound> ambientSound();
+
+    /**
+     * The mood sound settings.
+     *
+     * @return the mood sound settings.
+     */
+    Optional<MoodSound> moodSound();
+
+    /**
+     * The addition sound settings.
+     *
+     * @return the addition sound settings.
+     */
+    Optional<AdditionSound> additionSound();
+
+    /**
+     * Specific music that should be played in the biome.
+     *
+     * @return the music entries.
+     */
+    List<MusicEntry> music();
+
+    /**
+     * The game smoothly transitions between the current music volume
+     * and the new volume when entering the biome.
+     *
+     * @return the music volume of this biome.
+     */
+    float musicVolume();
+
+    /**
+     * This method applies the unique biome grass color modifiers
+     * depending on the coordinates of the block.
+     *
+     * @param original the initial grass color.
+     * @param location the location of the block.
+     * @return the modified grass color.
+     */
+    Color modifyGrassColor(Color original, Location location);
+}

paper-api/src/main/java/io/papermc/paper/world/biome/effects/AdditionSound.java

@@ -0,0 +1,24 @@
+package io.papermc.paper.world.biome.effects;
+
+import org.bukkit.Sound;
+import org.jetbrains.annotations.Range;
+
+/**
+ * Settings for additions sound.
+ */
+public interface AdditionSound {
+    /**
+     * One sound event — The additions sound.
+     *
+     * @return the sound event.
+     */
+    Sound sound();
+
+    /**
+     * The probability to start playing the sound per tick.
+     *
+     * @return the probability.
+     */
+    @Range(from = 0, to = 1)
+    double tickChance();
+}

paper-api/src/main/java/io/papermc/paper/world/biome/effects/MoodSound.java

@@ -0,0 +1,40 @@
+package io.papermc.paper.world.biome.effects;
+
+import org.bukkit.Sound;
+
+/**
+ * Settings for mood sound.
+ */
+public interface MoodSound {
+    /**
+     * One sound event — The mood sound.
+     *
+     * @return the mood sound.
+     */
+    Sound sound();
+
+    /**
+     * The minimum delay between mood sound plays.
+     *
+     * @return the minimum delay.
+     */
+    int tickDelay();
+
+    /**
+     * Determines the cubic range of possible positions
+     * to find place to play the mood sound.
+     * The player is at the center of the cubic range,
+     * and the edge length is {@code 2 * blockSearchExtent}.
+     *
+     * @return the block search extent.
+     */
+    int blockSearchExtent();
+
+    /**
+     * The higher the value makes the
+     * sound source further away from the player.
+     *
+     * @return the sound position offset.
+     */
+    double offset();
+}

paper-api/src/main/java/io/papermc/paper/world/biome/effects/MusicEntry.java

@@ -0,0 +1,40 @@
+package io.papermc.paper.world.biome.effects;
+
+import org.bukkit.Sound;
+
+public interface MusicEntry {
+    /**
+     * One sound event — The music sound.
+     *
+     * @return the music sound.
+     */
+    Sound sound();
+
+    /**
+     * The min delay between two music.
+     *
+     * @return the min delay.
+     */
+    int minDelay();
+
+    /**
+     * The max delay between two music.
+     *
+     * @return the max delay.
+     */
+    int maxDelay();
+
+    /**
+     * Whether to replace music which is already playing.
+     *
+     * @return true if the music should be replaced.
+     */
+    boolean replaceCurrentMusic();
+
+    /**
+     * The weight of the music.
+     *
+     * @return the weight.
+     */
+    int weight();
+}

paper-api/src/main/java/io/papermc/paper/world/biome/effects/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Package that contains classes that are part biome effects.
+ */
+@NullMarked
+package io.papermc.paper.world.biome.effects;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/io/papermc/paper/world/biome/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Package for biome-related classes.
+ */
+@NullMarked
+package io.papermc.paper.world.biome;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/org/bukkit/ChunkSnapshot.java

@@ -1,5 +1,6 @@
 package org.bukkit;
 
+import io.papermc.paper.world.biome.BiomeClimate;
 import org.bukkit.block.Biome;
 import org.bukkit.block.data.BlockData;
 import org.jetbrains.annotations.NotNull;
@@ -139,7 +140,11 @@ public interface ChunkSnapshot {
      * @param y Y-coordinate (world minHeight (inclusive) - world maxHeight (exclusive))
      * @param z Z-coordinate (0-15)
      * @return temperature at given coordinate
+     * @see Biome#climate()
+     * @see BiomeClimate#adjustedTemperature(Location)
+     * @deprecated Get the temperature from the biome instead
      */
+    @Deprecated(since = "1.21.4")
     double getRawBiomeTemperature(int x, int y, int z);
 
     /**