Add PlayerInsertLecternBookEvent [1.20 port] (#7305)

* Add PlayerInsertLecternBookEvent

* Rebase

Additionally, moves the event call higher up and removes the lectern
block state clone from the event.

* jSpecify

* Shrink correctly

* style fixups

* move methods

* rename param to cancel

* fix javadocs

* more javadoc fixes

* fix co-author on patch from yesterday

* last fix

---------

Co-authored-by: Mariell Hoversholm <proximyst@proximyst.com>
Co-authored-by: Bjarne Koll <lynxplay101@gmail.com>

patches/api/0112-Expand-Explosions-API.patch

@@ -5,7 +5,7 @@ Subject: [PATCH] Expand Explosions API
 
 Add Entity as a Source capability, and add more API choices, and on Location.
 
-Co-authored-by: Slqmy <90862990+Slqmy@users.noreply.github.com>
+Co-authored-by: Esoteric Enderman <90862990+EsotericEnderman@users.noreply.github.com>
 Co-authored-by: Bjarne Koll <lynxplay101@gmail.com>
 
 diff --git a/src/main/java/org/bukkit/Location.java b/src/main/java/org/bukkit/Location.java

patches/api/0493-Add-PlayerInsertLecternBookEvent.patch

@@ -0,0 +1,108 @@
+From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
+From: Mariell Hoversholm <proximyst@proximyst.com>
+Date: Sat, 29 Aug 2020 21:55:41 +0200
+Subject: [PATCH] Add PlayerInsertLecternBookEvent
+
+
+diff --git a/src/main/java/io/papermc/paper/event/player/PlayerInsertLecternBookEvent.java b/src/main/java/io/papermc/paper/event/player/PlayerInsertLecternBookEvent.java
+new file mode 100644
+index 0000000000000000000000000000000000000000..6d31e0c30f0389eeaf44335bd842ca3e1d0212eb
+--- /dev/null
++++ b/src/main/java/io/papermc/paper/event/player/PlayerInsertLecternBookEvent.java
+@@ -0,0 +1,96 @@
++package io.papermc.paper.event.player;
++
++import com.google.common.base.Preconditions;
++import org.bukkit.block.Block;
++import org.bukkit.block.BlockState;
++import org.bukkit.block.Lectern;
++import org.bukkit.entity.Player;
++import org.bukkit.event.Cancellable;
++import org.bukkit.event.HandlerList;
++import org.bukkit.event.player.PlayerEvent;
++import org.bukkit.inventory.ItemStack;
++import org.jetbrains.annotations.ApiStatus;
++import org.jspecify.annotations.NullMarked;
++
++/**
++ * This event is called when a player clicks on a lectern to insert a book.
++ * If this event is cancelled the player will keep the book and the lectern will remain empty.
++ */
++@NullMarked
++public class PlayerInsertLecternBookEvent extends PlayerEvent implements Cancellable {
++
++    private static final HandlerList HANDLER_LIST = new HandlerList();
++    private boolean cancelled = false;
++    private final Block block;
++    private ItemStack book;
++
++    @ApiStatus.Internal
++    public PlayerInsertLecternBookEvent(final Player player, final Block block, final ItemStack book) {
++        super(player);
++        this.block = block;
++        this.book = book;
++    }
++
++    /**
++     * Gets the block of the lectern involved in this event.
++     *
++     * @return the block of the lectern
++     */
++    public Block getBlock() {
++        return this.block;
++    }
++
++    /**
++     * Fetches the lectern block state that was part of this event.
++     * This method constructs a new snapshot {@link org.bukkit.block.BlockState}.
++     *
++     * @return a new lectern state snapshot of the involved lectern
++     * @throws IllegalStateException if the block at {@link #getBlock()} is no longer a lectern
++     */
++    public Lectern getLectern() {
++        final BlockState state = this.getBlock().getState();
++        Preconditions.checkState(state instanceof Lectern, "Block state of lectern block is no longer a lectern tile state!");
++        return (Lectern) state;
++    }
++
++    /**
++     * Returns the itemstack the player tried to insert. This is a copy of the item,
++     * changes made to this itemstack will not affect the book that is being placed in the lectern.
++     * If you want to mutate the item stack that ends up in the lectern, use {@link #setBook(ItemStack)}.
++     *
++     * @return the book that is being placed
++     */
++    public ItemStack getBook() {
++        return this.book.clone();
++    }
++
++    /**
++     * Sets the itemstack to insert into the lectern.
++     *
++     * @param book the book to insert (non book items will leave the lectern in a locked
++     *             state as the menu cannot be opened, preventing item extraction)
++     */
++    public void setBook(final ItemStack book) {
++        Preconditions.checkArgument(book != null, "Cannot set book to null");
++        this.book = book.clone();
++    }
++
++    @Override
++    public boolean isCancelled() {
++        return this.cancelled;
++    }
++
++    @Override
++    public void setCancelled(final boolean cancel) {
++        this.cancelled = cancel;
++    }
++
++    @Override
++    public HandlerList getHandlers() {
++        return HANDLER_LIST;
++    }
++
++    public static HandlerList getHandlerList() {
++        return HANDLER_LIST;
++    }
++}

patches/server/0203-Expand-Explosions-API.patch

@@ -5,7 +5,7 @@ Subject: [PATCH] Expand Explosions API
 
 Add Entity as a Source capability, and add more API choices, and on Location.
 
-Co-authored-by: Slqmy <90862990+Slqmy@users.noreply.github.com>
+Co-authored-by: Esoteric Enderman <90862990+EsotericEnderman@users.noreply.github.com>
 Co-authored-by: Bjarne Koll <lynxplay101@gmail.com>
 
 diff --git a/src/main/java/net/minecraft/server/level/ServerLevel.java b/src/main/java/net/minecraft/server/level/ServerLevel.java

patches/server/1063-Add-PlayerInsertLecternBookEvent.patch

@@ -0,0 +1,36 @@
+From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
+From: Mariell Hoversholm <proximyst@proximyst.com>
+Date: Sun, 29 Sep 2024 16:21:26 +0200
+Subject: [PATCH] Add PlayerInsertLecternBookEvent
+
+
+diff --git a/src/main/java/net/minecraft/world/level/block/LecternBlock.java b/src/main/java/net/minecraft/world/level/block/LecternBlock.java
+index ebb79907391fe3128d3d16fbe9d8cb0b22bcc9f7..3a1e2f62b297f384cc0dcfb828e523a37c703d6f 100644
+--- a/src/main/java/net/minecraft/world/level/block/LecternBlock.java
++++ b/src/main/java/net/minecraft/world/level/block/LecternBlock.java
+@@ -157,7 +157,24 @@ public class LecternBlock extends BaseEntityBlock {
+         BlockEntity tileentity = world.getBlockEntity(pos);
+ 
+         if (tileentity instanceof LecternBlockEntity tileentitylectern) {
+-            tileentitylectern.setBook(stack.consumeAndReturn(1, user));
++            // Paper start - Add PlayerInsertLecternBookEvent
++            ItemStack eventSourcedBookStack = null;
++            if (user instanceof final net.minecraft.server.level.ServerPlayer serverPlayer) {
++                final io.papermc.paper.event.player.PlayerInsertLecternBookEvent event = new io.papermc.paper.event.player.PlayerInsertLecternBookEvent(
++                    serverPlayer.getBukkitEntity(),
++                    org.bukkit.craftbukkit.block.CraftBlock.at(world, pos),
++                    org.bukkit.craftbukkit.inventory.CraftItemStack.asCraftMirror(stack.copyWithCount(1))
++                );
++                if (!event.callEvent()) return;
++                eventSourcedBookStack = org.bukkit.craftbukkit.inventory.CraftItemStack.unwrap(event.getBook());
++            }
++            if (eventSourcedBookStack == null) {
++                eventSourcedBookStack = stack.consumeAndReturn(1, user);
++            } else {
++                stack.consume(1, user);
++            }
++            tileentitylectern.setBook(eventSourcedBookStack);
++            // Paper end - Add PlayerInsertLecternBookEvent
+             LecternBlock.resetBookState(user, world, pos, state, true);
+             world.playSound((Player) null, pos, SoundEvents.BOOK_PUT, SoundSource.BLOCKS, 1.0F, 1.0F);
+         }