What's Changed

• Fix off-by-one error in villager level encoding by @PeyaPeyaPeyang in #3000

New Contributors

• @PeyaPeyaPeyang made their first contribution in #3000

Full Changelog: 2025.12.20b-1.21.11...2025.12.20c-1.21.11

Full Changelog: 2025.12.20-1.21.11...2025.12.20b-1.21.11

The 1.21.11 branch has now been merged, thanks to all who tested and contributed to it!

Environment Attributes & Timelines

See minecraft.wiki Environment Attributes and Timelines for exact format details.

Environment attributes bring a pretty notable breaking change to the Biome and DimensionType API (many fields have changed, all of the removed fields are now configured via Environment Attributes as well as many new options).

Both Biome.Builder and DimensionType.Builder have a new setAttribute(EnvironmentAttribute<T>, T) to override a single attribute. Biome additionally has an option to modify an inherited attribute (reminder: attributes are merged with their parent) via modifyAttribute(EnvironmentAttribute<T>, Modifier<T, Arg>, Arg). The available modifiers for a given attribute can be observed in the operators argument of the EnvironmentAttributeTypes initializers. For example, when modifying a boolean typed attribute, the BOOLEAN_OPERATORS are available (AND, NAND, OR, NOR, XOR, XNOR).

Timelines are a system for applying Environment Attribute modifiers to a dimension interpolated over time. You can choose the period and add keyframes to apply modifiers over time with configurable interpolation function.

Timelines must be registered in their registry (MinecraftServer#getTimelineRegistry), and then may be added to a DimensionType as a registry tag.

An example of some of these APIs is available below.

var myDimension = DimensionType.builder()
        .setAttribute(EnvironmentAttribute.SKY_COLOR, new Color(0x77aaff))
        .setAttribute(EnvironmentAttribute.CLOUD_COLOR, new AlphaColor(0xFFFF0000))
        .setAttribute(EnvironmentAttribute.FOG_START_DISTANCE, 0f)
        .setAttribute(EnvironmentAttribute.FOG_END_DISTANCE, 1000f)
        .build();
var myBiome = Biome.builder()
        // Force the cloud height to be 45 when in this biome no matter the dimension type configuration
        .setAttribute(EnvironmentAttribute.CLOUD_HEIGHT, 45f)
        // Enable bees stay in hive ONLY if the parent (dimension) is also enabled
        .modifyAttribute(EnvironmentAttribute.BEES_STAY_IN_HIVE,
                         EnvironmentAttribute.Modifier.Boolean.AND,
                         true)
        .build();

var myTimeline = Timeline.builder()
        .periodTicks(24000) // 1 day
        .tracks(Map.of(
                // Move cloud height up by 20 at 12000 and then back to 0 with interpolation
                EnvironmentAttribute.CLOUD_HEIGHT, new Timeline.Track<>(
                        EnvironmentAttribute.Modifier.Float.ADD,
                        List.of(
                                new Timeline.Keyframe<>(0, 0f),
                                new Timeline.Keyframe<>(12000, 20f),
                                new Timeline.Keyframe<>(24000, 0f)
                        ),
                        EaseFunction.IN_OUT_CUBIC
                )
        ))
        .build();

This API is probably non-final (Mojang has also labelled this system experimental), expect some tweaks and improvements over time.

New in Minecraft

• (Zombie) Nautilus, Camel Husk, and Parched are now spawnable with the associated EntityType and NautilusMeta/ZombieNautilusMeta/CamelHuskMeta/ParchedMeta.
• New data components are USE_EFFECTS, MINIMUM_ATTACK_CHARGE, DAMAGE_TYPE, ATTACK_RANGE, PIERCING_WEAPON, KINETIC_WEAPON, SWING_ANIMATION, and ZOMBIE_NAUTILUS_VARIANT.
• The new stab attack (also can be used for click detection) can be observed via the new PlayerStabEvent.

Misc Changes

• Transfers are now supported (#2484) thanks to @mudkipdev
• Absolute and relative block batches now provide their inverse in the callback function (when inverse is calculated) (#2981) thanks to @TropicalShadow
• Removed previously deprecated Auth related classes (MojangAuth, VelocityProxy, and BungeeCordProxy).
• Minestom now provides the common set of easing functions in the Ease util class.
• Unsafe-free collections are being used by default, you can switch back to using Unsafe if you notice major regressions via ServerFlag#UNSAFE_COLLECTIONS.

Misc Future Tasks

• Correctly processing entity passenger/vehicle offsets remain as TODO items from 1.20.6.
• API to send and automatically wait for code of conduct acceptance from 1.21.9.

Full Changelog: 2025.12.19-1.21.10...2025.12.20-1.21.11

What's Changed

• Add cloud_height by @thecodertommy in #2956
• Fix: scoreboard updateScore not implemented by @Sybsuper in #2966
• feature: Use minestom flattener in ANSI serializer by @kezz in #2968
• fix: Ignored empty compound serialisation flag by @SorkoPiko in #2961
• Implement ComponentHolding for UpdateScorePacket by @cosrnic in #2977
• fix: don't include null players in SetImpl::size() (as in iterator()) by @SorkoPiko in #2979
• Refactor Tag into Impl pattern & Re-enable jcstress-tests by @kermandev in #2952
• feature: Implement Adventure click callbacks by @kezz in #2970
• fix: precision loss in SoundEffectPacket coordinates by @unsurprisable in #2986
• fix: Simple light optimization by @kermandev in #2976
• refactor: ensure tests use JUnit assertions by @SorkoPiko in #2990
• Implement transfer intent by @mudkipdev in #2484

New Contributors

• @thecodertommy made their first contribution in #2956
• @Sybsuper made their first contribution in #2966
• @unsurprisable made their first contribution in #2986

Full Changelog: 2025.10.31-1.21.10...2025.12.19-1.21.10

What's Changed

• Update jitpack.yml to use 25-graal by @kermandev in #2942
• fix: update entity CUSTOM_DATA handling to use the new DataComponent data shape by @Bloeckchengrafik in #2953
• fix: change Armadillo class to extend AgeableMob to fix metadata indices disconnecting clients by @Bloeckchengrafik in #2954
• docs: Add example gamemode switcher implementation to demo server by @SorkoPiko in #2957
• implement PlayerInstanceEvent in PlayerSpectateEvent by @TropicalShadow in #2915
• Fix broken ObjectComponent's PlayerHead by @kermandev in #2960

New Contributors

• @SorkoPiko made their first contribution in #2957

Full Changelog: 2025.10.18-1.21.10...2025.10.31-1.21.10

What's Changed

• Add BlockEntityType, fix ENTITY_DATA/BLOCK_ENTITY_DATA comps by @mworzala in #2949

Full Changelog: 2025.10.11-1.21.10...2025.10.18-1.21.10

Minestom 1.21.10

The 1.21.10 (including 1.21.9) branch has now been merged, thanks to all who tested and contributed to it!

Java 25

Minestom tracks the latest LTS version of Java. Since Java 25 has been released, it is now the minimum required version of Java to use Minestom. To use Java 25 you must be on IntelliJ IDEA 2025.2 or higher.

In gradle (Kotlin), you can set the Java version as such:

java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(25))    
    }
}

New in Minecraft

This is a new segment to these release notes, a high level description of how some of the new Minecraft features appear in Minestom:

• Mannequins and Copper Golems are now spawnable with the associated EntityType and MannequinMeta/CopperGolemMeta.
  • Note: Some fields from PlayerMeta were moved to the common AvatarMeta between player/mannequin. Offsets may have changed for those editing metadata manually for player entities.
• Object text components may be used with the adventure API, see Javadocs.
• The server code of conduct may be sent during configuration with the CodeOfConductPacket, at which point you should block the AsyncPlayerConfigurationEvent until receiving a ClientAcceptCodeOfConductPacket.

Misc Changes

• The IChunkLoader interface has been renamed to ChunkLoader.
• Minestom now tracks the server and client connection states separately, and play->configuration state changes only occur between ticks. These changes significantly improve stability when reentering the configuration phase from play. As such, PlayerConnection#getConnectionState has been fatally deprecated in favor #getServerState and #getClientState. When updating, #getConnectionState can be translated directly into #getClientState to preserve prior behavior. However, some logic may benefit from being side-state aware around configuration swaps.
• Block collision and occlusion shapes are now distinct, they can be accessed with myBlock.registry().collisionShape() and myBlock.registry().occlusionShape() respectively.
• PlayerChangeHeldSlotEvent#getOldSlot now returns a byte (inline with other methods about player held slots) instead of an int.
• The ResourceLocation argument now uses an Adventure Key instead of a raw string.
• Adventure API, Key, and NBT are exported as transitive dependencies of Minestom.
• Fastutil is no longer exported as a transitive dependency of Minestom.

Misc Future Tasks

• Receiving transfers and correctly processing entity passenger/vehicle offsets remain as TODO items from 1.20.6.
• API to send and automatically wait for code of conduct acceptance from 1.21.9.

Full Changelog: 2025.10.05-1.21.8...2025.10.11-1.21.10

What's Changed

• Ensure nullability constraints at runtime for Codecs by @kermandev in #2908
• Add support for entity head rotation by @TogAr2 in #2899
• Instance#generateChunk by @TheMode in #2933
• Fix generateChunk locking by @TheMode in #2934
• Fix command condition bypass bug by @mudkipdev in #2932

Full Changelog: 2025.10.04-1.21.8...2025.10.05-1.21.8

What's Changed

• fix: incorrect minecart meta by @ThatGravyBoat in #2920
• add subcommands vararg by @AhmadNasser04 in #2918
• Add Sidebar title getter by @mudkipdev in #2928
• Switch back to adventures javadoc by @kermandev in #2930
• optimize palette resizing by @AidanMars2 in #2877

New Contributors

• @AhmadNasser04 made their first contribution in #2918

Full Changelog: 2025.09.13-1.21.8...2025.10.04-1.21.8

What's Changed

• Add the pack UUID to the status event by @GreatWyrm in #2897
• Fix entity line of sight detection by @TogAr2 in #2901
• make sounds public by @DasBabyPixel in #2910
• UseItemListener call move with new rotation before PlayerUseItemEvent by @DasBabyPixel in #2911
• Resolve #2898 #2903 #2904 #2720 #2748 & more by @kermandev in #2909

Full Changelog: 2025.08.29-1.21.8...2025.09.13-1.21.8