Hard fork from our upstream​

While this may sound scary, we have bundled up some helpful disclaimers for each relevant user group down below. We are committed to making this process as smooth as possible for everyone. If any more questions arise, feel free to ask us on our Discord!

Click to expand...

Server owners / administrators​

Plugin developers​

Moving our old version branches to a new repo​

Paper contributors​

Paper fork developers​

Next steps/rough timeline​

1. We will spend the following weeks updating the repository by changing the patch structure and fixing endless patch conflicts from the updated decompiler and new set of local/parameter mappings.
2. Once that is done, we will push these builds as experimental builds to ensure we didn't break any backwards compatibility or introduced any new issues.
3. Once we have finished our tooling around forks and userdev, we will post an announcement on how to update forks and notify Paper contributors on how to properly update their pull requests to the new main branch.

TL;DR​

The 1.21.3 Update​

• Gerrygames for his work on Velocity
• electronicboy - https://github.com/sponsors/electronicboy
• jmp - https://github.com/sponsors/jpenilla
• kennytv
• Lulu13022002
• lynxplay - https://github.com/lynxplay
• Machine Maker - https://github.com/sponsors/Machine-Maker
• Noah - https://github.com/sponsors/NoahvdAa
• Owen1212055 - https://github.com/sponsors/Owen1212055
• SpaceWalkerRS
• Spottedleaf - https://www.patreon.com/Spottedleaf

Timings removal​

Server pausing when empty (disabled by default)​

Configurable entity despawn time​

Option to use old enderpearl behavior​

Invulnerability damage reduction​

String duplication fixed by Mojang​

Server pausing​

Extensive Item DataComponent API​

ItemStack itemStack = new ItemStack(Material.DIAMOND_HELMET);

// Update parts of the already existing equippable data:
// Use the netherrite helmet model when worn and change the equip sound
Equippable.Builder equippable = itemStack.getData(DataComponentTypes.EQUIPPABLE).toBuilder()
    .model(Material.NETHERITE_HELMET.getDefaultData(DataComponentTypes.EQUIPPABLE).model())
    .equipSound(SoundEventKeys.ENTITY_GHAST_HURT);
itemStack.setData(DataComponentTypes.EQUIPPABLE, equippable);

// Create new food data
FoodProperties.Builder food = FoodProperties.food()
    .canAlwaysEat(true)
    .nutrition(2)
    .saturation(3.5f);
itemStack.setData(DataComponentTypes.FOOD, food);

Other API changes​

• Added PlayerItemGroupCooldownEvent to listen to cooldowns that may not be directly associated with using an item, since cooldowns are now added via cooldown groups rather than item types. The already existing PlayerItemCooldownEvent extends the new event.
• Due to Vanilla changes to relative teleportation, TeleportFlag.Relative enum members have been deprecated. The new members with more appropriate names are: VELOCITY_X, VELOCITY_Y, VELOCITY_Z, and VELOCITY_ROTATION
• EntityDamageEvent now has the INVULNERABILITY_REDUCTION cause
• Our auto-generated Vanilla key classes (e.g. SoundEventKeys) now implement Key, so they can be used in API like the data componenents API directly
• You can now create custom painting art via API and the new RegistryEvents.PAINTING_VARIANT. More are coming over time as well - see https://docs.papermc.io/paper/dev/registries for more info on how to use them

The 1.21 Update​

• 4drian3d and Gerrygames for their work on Velocity
• electronicboy - https://github.com/sponsors/electronicboy
• jmp - https://github.com/sponsors/jpenilla
• kennytv
• lynxplay - https://github.com/lynxplay
• Lulu13022002
• Machine Maker - https://github.com/sponsors/Machine-Maker
• Ollie for his work on our docs
• Spottedleaf - https://www.patreon.com/Spottedleaf
• Owen1212055 - https://github.com/sponsors/Owen1212055
• and finally tal5, Dawon, yannicklamprecht and Doc94 for additional help!

spark profiler inclusion in Paper​

Configuration changes​

• merge-radius.exp: 3->-1(disabled). vanilla has its own less aggressive merging logic, but generally xp orbs were not a large performance concern; otherwise we might instead offer new options to change vanilla’s merge logic
• merge-radius.item: 2.5->0.5, reflecting the vanilla default, since the increased value was often seen as disruptive. If you expect large number of the same item types to be lying around close to one another, you can increase this again
• entity-activation-range.raider: 48->64
• Various values under entity-tracking-range have been increased to make sure you can actually see monsters and players attacking you from farther away (e.g. no longer running into invisible ghasts shooting at you in the nether. Note that this does not affect ticking, only whether they are sent to a player)
  • players: 48->128
  • animals: 48->96
  • monsters: 48->96
  • misc: 32->96

Slower than usual startup​

'Done'-message changes​

The .paper-remapped directory​

Attribute modifiers​

Removed chunk gen delegation and regeneration methods​

ItemStack and ItemMeta (again)​

Other changes​

• End gateway teleportation cancellation doesn't reset the portal cooldown, so you should use EntityPortalEnterEvent with PortalType.END_GATEWAY to check for initial entries
• Projectile#getWeapon is now nullable

Opportunity to change the git commit author details in Paper commits​

• ViaVersion takes over two seconds longer to load (from a few hundred ms to 2.5 seconds)
• WorldEdit takes two and a half seconds longer (from about 1.5 to 4 seconds)
• CoreProtect takes a second and a half longer (on a clean setup with otherwise no measurable load time at all if rewriting is disabled)

The 1.20.5/6 Update​

• 4drian3d and Gerrygames for their work on Velocity
• electronicboy - https://github.com/sponsors/electronicboy
• jmp - https://github.com/sponsors/jpenilla
• lynxplay - https://github.com/lynxplay
• Lulu13022002
• Machine Maker - https://github.com/sponsors/Machine-Maker
• Noah - https://github.com/sponsors/NoahvdAa
• Ollie for his work on our docs
• Owen1212055 - https://github.com/sponsors/Owen1212055
• Spottedleaf - https://www.patreon.com/Spottedleaf

Java 21 requirement​

Item format changes​

spawnChunkRadius gamerule​

For Developers​

Mojang-mapped runtime without CB package relocation​

Brigadier Command API​

ItemStack and ItemMeta​

canPlaceOn and canBreak break​

ItemFlag behavioral changes​

That's it​

as always, BACKUP YO SHIT, so long, and thanks for the fish

Click to expand...

Announcing the end of life of Waterfall​

What is changing?​

What should I do?​

Future removal of CB package relocation + moving away from obfuscation at runtime​

How to make sure your plugin does not break​

private static final String CRAFTBUKKIT_PACKAGE = Bukkit.getServer().getClass().getPackage().getName();

public static String cbClass(String className) {
    return CRAFTBUKKIT_PACKAGE + "." + className);
}

Class.forName(cbClass("entity.CraftBee"))

String craftBukkitPackage = Bukkit.getServer().getClass().getPackage().getName();
// This is the *bad* part, including any other parsing of the version
String version = craftBukkitPackage.substring(craftBukkitPackage.lastIndexOf('.') + 1);
if (version.equals("v1_20_R3")) {
    // ...
} else {
  // Unsupported
}

// Paper method that was added in 2020
// Example value: 1.20.4
String minecraftVersion = Bukkit.getServer().getMinecraftVersion();

// Bukkit method that was added in 2011
// Example value: 1.20.4-R0.1-SNAPSHOT
String bukkitVersion = Bukkit.getServer().getBukkitVersion();

if (minecraftVersion.equals("1.20.4")) {
    // ...
} else {
  // Assume latest still works, or error as unsupported
  // Alternatively for extra compatibility, check if
  // the latest package version is valid by catching
  // ClassNotFoundException with: Class.forName("org.bukkit.craftbukkit.v1_20_R3.CraftServer")
}

As a server owner​

[11:46:19] [Server thread/ERROR]: Error occurred while enabling PLUGINNAME v1 (Is it up to date?)
java.lang.ArrayIndexOutOfBoundsException: Index 3 out of bounds for length 3
at ...

Click to expand...

Happy New Year from PaperMC!​

The Future​

Lifecycle API​

 @Override
    public void onEnable() {
        final LifecycleEventManager<Plugin> lifecycles = this.getLifecycleManager();
        lifecycles.registerEventHandler(LifecycleEvents.DUMMY_STATIC.newHandler(event -> {
            final DummyResourceRegistrar registrar = event.registrar();
            System.out.println("dummy_static hook FIRST");
        }).priority(-1));
        lifecycles.registerEventHandler(LifecycleEvents.DUMMY_STATIC.newHandler(event -> {
            final DummyResourceRegistrar registrar = event.registrar();
            System.out.println("dummy_static hook FOURTH (monitor)");
        }).monitor());
        lifecycles.registerEventHandler(LifecycleEvents.DUMMY_STATIC.newHandler(event -> {
            final DummyResourceRegistrar registrar = event.registrar();
            System.out.println("dummy_static hook THIRD");
        }).priority(100));
    }

Brigadier API​

CommandBuilder.of(plugin, "admin")
            .then(
                LiteralArgumentBuilder.<CommandSourceStack>literal("execute")
                    .redirect(Bukkit.getCommandDispatcher().getRoot().getChild("execute"))
            )
            .then(
                LiteralArgumentBuilder.<CommandSourceStack>literal("signed_message").then(
                    RequiredArgumentBuilder.argument("msg", VanillaArguments.signedMessage()).executes((context) -> {
                        MessageArgumentResponse argumentResponse = context.
                        getArgument("msg", MessageArgumentResponse.class); // Gets the raw argument.

                        // This is a better way of getting signed messages,
                        // includes the concept of "disguised" messages.
                        argumentResponse.resolveSignedMessage("msg", context)
                            .thenAccept((signedMsg) -> {
                                Component comp = Component.text("STATIC");
                                context.getSource()
                                            .getBukkitSender()
                                            .sendMessage(signedMsg, ChatType.SAY_COMMAND.bind(comp));
                            });

                        return 1;
                    })
                )
            ))
            .description("Cool command showcasing what you can do!")
            .aliases("alias_for_admin_that_you_shouldnt_use", "a")
            .register();

Registry Manipulation API​

static final TypedKey<GameEvent> NEW_EVENT = GameEventKeys.create(Key.key("machine_maker", "best_event"));

@Override
public void bootstrap(@NotNull BootstrapContext context) {
    final LifecycleEventManager<BootstrapContext> lifecycles = context.getLifecycleManager();

    // registers a new handler for the prefreeze event for the game event registry
    lifecycles.registerEventHandler(RegistryEvents.GAME_EVENT.preFreeze().newHandler(event -> {
        // the RegistryView provided here is writable so you can register new objects
        event.registry().register(NEW_EVENT, builder -> {
            builder.range(2);
        });
    }));
 
    // registers a handler for the addition event
    lifecycles.registerEventHandler(RegistryEvents.GAME_EVENT.newAdditionHandler(event -> {
        // checks if the object being registered is the block open game event
        if (event.key().equals(GameEventKeys.BLOCK_OPEN)) {
            // multiplies the range by 2
            event.builder().range(event.builder().range() * 2);
        }
    }));
}

Mache and Codebook​

Here's to a fantastic 2024!​

The 1.20.4 Update​

• Gerrygames, pkt77, and electroniccat for their work on Velocity
• Machine Maker - https://github.com/sponsors/Machine-Maker
• lynxplay - https://github.com/lynxplay
• jmp - https://github.com/sponsors/jpenilla
• Lulu13022002
• Owen1212055 - https://github.com/sponsors/Owen1212055
• Spottedleaf - https://www.patreon.com/Spottedleaf
• kennytv - https://github.com/sponsors/kennytv

Discord Update Announcements​

For Developers​

New API​

Keyed interface may be removed on some types​

Hangar login/signup via GitHub, Google, or Microsoft account​

The 1.20.2 Update​

• Paul19988, Redned235, and Gerrygames for their work on Velocity
• Machine Maker - https://github.com/sponsors/Machine-Maker
• Noah - https://github.com/sponsors/NoahvdAa
• lynxplay - https://github.com/lynxplay
• jmp - https://github.com/sponsors/jpenilla
• Lulu13022002
• MiniDigger - https://github.com/sponsors/MiniDigger
• Owen1212055 - https://github.com/sponsors/Owen1212055
• Spottedleaf - https://www.patreon.com/Spottedleaf
• kennytv - https://github.com/sponsors/kennytv

Velocity & Waterfall​

For Developers​

CraftBukkit package relocation​

• parse the relocated package version.
• call CB internals.

private static final String CRAFTBUKKIT_PACKAGE = Bukkit.getServer().getClass().getPackage().getName();

public static String cbClass(String clazz) {
    return CRAFTBUKKIT_PACKAGE + "." + clazz);
}

Class.forName(cbClass("entity.CraftBee"))

String craftBukkitPackage = Bukkit.getServer().getClass().getPackage().getName();
// This is the *bad* part, including any other parsing of the version
String version = craftBukkitPackage.substring(craftBukkitPackage.lastIndexOf('.') + 1);
if (version.equals("v1_20_R1")) {
    // ...
} else {
  // Unsupported
}

// Paper method that was added in 2020
// Example value: 1.20.1
String minecraftVersion = Bukkit.getServer().getMinecraftVersion();

// Bukkit method that was added in 2011
// Example value: 1.20.1-R0.1-SNAPSHOT
String bukkitVersion = Bukkit.getServer().getBukkitVersion();

if (minecraftVersion.equals("1.20.1")) {
    // ...
} else {
  // Assume latest still works, or error as unsupported
  // Alternatively for extra compatibility, check if
  // the latest package version is valid by catching
  // ClassNotFoundException with: Class.forName("org.bukkit.craftbukkit.v1_20_R1.CraftServer")
}

Future changes regarding API enums​

1.20.2 API changes​

Hangar​

The 1.20(.1) Update​

• @Machine Maker - https://github.com/sponsors/Machine-Maker
• @Spottedleaf - https://www.patreon.com/Spottedleaf
• @Owen1212055 - https://github.com/sponsors/Owen1212055
• @lynxplay - https://github.com/lynxplay
• @Noah - https://github.com/sponsors/NoahvdAa
• @kennytv - https://github.com/sponsors/kennytv

For Developers​

• SmithingRecipe has been replaced with SmithingTrimRecipe and SmithingTransformRecipe
• InventoryType.SMITHING now uses 1.20's new smithing table interface
• Sign#isEditable() has been deprecated in favor of a new method called isWaxed, same for its setter

• AsyncChatDecorateEvent#isPreview()
• PlayerLocaleChangeEvent
• PlayerInitialSpawnEvent
• WorldBorder#isInBounds(Location)
• EntityTransformedEvent
• ItemStackRecipeChoice
• HeightmapType
  • All associated methods in Location and World
• All deprecated or removed GoalKeys in VanillaGoal
• StructureLocateEvent (not the new StructuresLocateEvent)
• Duplicate Effects
• World API
  • World#hasSkylight()
  • World#hasBedrockCeiling()
  • World#doesBedWork()
  • World#doesRespawnAnchorWork()

Hangar​

Experimental channel for builds​

• adding other authors to your project,
• creating organizations with projects under them,
• managing roles per project or per organization (such as editor or developer)
• combined releases with multiple jars or external links per platform,
• customizable release channels (such as beta or snapshot),
• a proper, documented API to upload and download plugins (OpenAPI yaml),
• creating multiple project description/wiki pages,
• selecting compatibility with minor Minecraft versions as well as specific Velocity versions,
• additional tags to mark a plugin as an addon, a library, or Folia compatible,
• a secure account system with support for modern multi factor authentication standards like TOTP and WebAuthN (YubiKeys are supported!)

Otherwise we hope to see you and your plugins on Hangar over at https://hangar.papermc.io/​

The 1.19.4 Update​

• @kennytv - https://github.com/sponsors/kennytv
• @Machine Maker - https://github.com/sponsors/Machine-Maker
• @Owen1212055 - https://github.com/sponsors/Owen1212055
• Gerrygames (for help with Velocity)

Experimental Channel for Builds​

Website Overhaul​

For Developers​

• Experimental features have representation in API, but are marked as experimental and are subject to changes, as Mojang might still change them in major ways before they land in 1.20. See here for more information on experimental features in general.
• Using adventure's ClickEvent.callback methods, you can now easily register message click event callbacks without having to keep track of them yourself. This code for example will create a click event to open a book that can be used for up to 2 minutes and has 5 uses:
  
  Java:

  ClickCallback.Options options = ClickCallback.Options.builder()
      .lifetime(Duration.ofMinutes(2))
      .uses(5)
      .build();
  ClickEvent clickEvent = ClickEvent.callback(
      audience -> audience.openBook(book),
      options
  );
  player.sendMessage(Component.text().content("Click me!").clickEvent(clickEvent));

  In these methods, you can also make sure only a certain player/players with a certain permission are allowed to use the callback.
• LivingEntity#setHurtDirection throws an UnsupportedOperationException if called on a non-player
• HopperMinecart#setCooldown and getCooldown throw UnsupportedOperationException

The 1.19.3 Update​

• @kennytv - https://github.com/sponsors/kennytv
• @Machine Maker - https://github.com/sponsors/Machine-Maker
• @Owen1212055 - https://github.com/sponsors/Owen1212055
• @Noah - https://github.com/sponsors/NoahvdAa
• @jmp - https://github.com/sponsors/jpenilla/
• FiXed (for his work on Velocity)
• @electronicboy - https://paypal.me/ShaneFreeder

Experimental Features​

For Developers​

The 1.19.1 Update​

Chat Signing and Reporting Concerns​

Chunk System Rewrite​

The 1.19 Update​

• @kennytv - https://github.com/sponsors/kennytv
• @Machine Maker - https://github.com/sponsors/Machine-Maker
• @Spottedleaf - https://www.patreon.com/Spottedleaf
• @Owen1212055 - https://github.com/sponsors/Owen1212055
• @Noah - https://github.com/sponsors/NoahvdAa
• @jmp - https://github.com/sponsors/jpenilla/
• @MiniDigger - https://github.com/sponsors/MiniDigger
• @sulu
• CoreyShupe/FiXed
• @electronicboy - https://paypal.me/ShaneFreeder
• @FivePB
• @Michael
• @aurora - https://github.com/sponsors/aurorasmiles

Major Configuration Changes​

For Developers​

Experimental channel for builds​

The 1.18.2 Update​

• @kennytv - https://github.com/sponsors/kennytv
• @Machine Maker - https://github.com/sponsors/Machine-Maker
• @jmp - https://github.com/sponsors/jpenilla/
• @kashike - https://github.com/sponsors/kashike
• @Spottedleaf - https://www.patreon.com/Spottedleaf
• @electronicboy - https://www.paypal.com/paypalme/ShaneFreeder

For Developers​

Docs​

The 1.18 update​

• @kennytv - https://github.com/sponsors/kennytv
• @jmp - https://www.patreon.com/jmp_
• @Machine Maker - https://github.com/sponsors/Machine-Maker
• @MiniDigger - https://github.com/sponsors/MiniDigger
• @Spottedleaf - https://www.patreon.com/Spottedleaf
• @DenWav
• @JRoy
• @stonar96

For Developers​

1. Add Paper’s maven repository to your Gradle plugin repositories in your settings.gradle.kts.
2. Add the Paperweight Userdev Gradle plugin to your build config with the id io.papermc.paperweight.userdev, keeping the version in sync with the paperweight version used in Paper.
3. Add the development bundle to your dependencies.
4. Make the assemble task depend on the reobfJar task.

​

Miscellaneous​