Add new Lidded API, deprecating existing bukkit Lidded API. Adds PlayerLiddedOpenEvent

paper-api/src/main/java/io/papermc/paper/block/LidMode.java

@@ -0,0 +1,50 @@
+package io.papermc.paper.block;
+
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Represents how the lid of a block behaves.
+ */
+@NullMarked
+public enum LidMode {
+    /**
+     * The default lid mode, the lid will open and close based on player interaction.
+     * <p>
+     * the state used for this is provided with {@link Lidded#getTrueLidState()}
+     */
+    DEFAULT,
+
+    /**
+     * The lid will be forced open, regardless of player interaction.
+     * <p>
+     * This needs to be manually unset with another call to {@link Lidded#setLidMode(LidMode)}.
+     */
+    FORCED_OPEN,
+
+    /**
+     * The lid will be forced closed, regardless of player interaction.
+     * <p>
+     * This needs to be manually unset with another call to {@link Lidded#setLidMode(LidMode)}.
+     */
+    FORCED_CLOSED,
+
+    /**
+     * The lid will be forced open until at least one player has opened it.
+     * <p>
+     * It will then revert to {@link #DEFAULT}.
+     * <p>
+     * If at least one player is viewing it when this is set, it will immediately revert to
+     * {@link #DEFAULT}.
+     */
+    OPEN_UNTIL_VIEWED,
+
+    /**
+     * The lid will be forced closed until all players currently viewing it have closed it.
+     * <p>
+     * It will then revert to {@link #DEFAULT}.
+     * <p>
+     * If no players are viewing it when this is set, it will immediately revert to
+     * {@link #DEFAULT}.
+     */
+    CLOSED_UNTIL_NOT_VIEWED
+}

paper-api/src/main/java/io/papermc/paper/block/LidState.java

@@ -0,0 +1,9 @@
+package io.papermc.paper.block;
+
+import org.jspecify.annotations.NullMarked;
+
+@NullMarked
+public enum LidState {
+    OPEN,
+    CLOSED
+}

paper-api/src/main/java/io/papermc/paper/block/Lidded.java

@@ -0,0 +1,37 @@
+package io.papermc.paper.block;
+
+import org.bukkit.block.TileState;
+import org.jspecify.annotations.NullMarked;
+
+@NullMarked
+public interface Lidded extends TileState {
+
+    /**
+     * Gets the current state of the block, respecting the lidded mode.
+     *
+     * @return the effective lid state
+     */
+    LidState getEffectiveLidState();
+
+    /**
+     * Gets how the lid would be without any lidded mode, based on players interacting with the block.
+     * @return the true lid state
+     */
+    LidState getTrueLidState();
+
+    /**
+     * Gets the current lid mode of the block.
+     *
+     * @return the lid mode
+     */
+    LidMode getLidMode();
+
+    /**
+     * Sets the lid mode of the block.
+     *
+     * @param mode the new lid mode
+     * @return the actually set lid mode
+     */
+    LidMode setLidMode(LidMode mode);
+
+}

paper-api/src/main/java/io/papermc/paper/event/player/PlayerLiddedOpenEvent.java

@@ -0,0 +1,89 @@
+package io.papermc.paper.event.player;
+
+import io.papermc.paper.block.LidMode;
+import io.papermc.paper.block.LidState;
+import io.papermc.paper.block.Lidded;
+import org.bukkit.block.Block;
+import org.bukkit.entity.Player;
+import org.bukkit.event.Cancellable;
+import org.bukkit.event.HandlerList;
+import org.bukkit.event.player.PlayerEvent;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Called when a player opens a {@link Lidded} block.
+ *
+ * <p>
+ * This is called every time a player opens a {@link Lidded} block
+ * regardless of if the lid is already open (e.g. multiple players).
+ * <p>
+ * Cancelling this event prevents the player from being considered in other {@link Lidded} methods:
+ * they will not contribute to the {@link Lidded#getTrueLidState()} and {@link Lidded#getEffectiveLidState()}.
+ * <p>
+ * This event is called twice for double chests, once for each half.
+ */
+@NullMarked
+public class PlayerLiddedOpenEvent extends PlayerEvent implements Cancellable {
+
+    private static final HandlerList HANDLER_LIST = new HandlerList();
+    private final Lidded blockState;
+    private final Block block;
+    private boolean cancelled;
+
+    @ApiStatus.Internal
+    public PlayerLiddedOpenEvent(final @NotNull Player who, final @NotNull Lidded blockState, final @NotNull Block block) {
+        super(who);
+        this.cancelled = false;
+        this.blockState = blockState;
+        this.block = block;
+    }
+
+
+    @Override
+    public boolean isCancelled() {
+        return cancelled;
+    }
+
+    @Override
+    public void setCancelled(final boolean cancel) {
+        this.cancelled = cancel;
+    }
+
+    /**
+     * Gets the {@link Lidded} block involved in this event.
+     * @return the lidded block
+     */
+    @NotNull
+    public Lidded getLidded() {
+        return blockState;
+    }
+
+    /**
+     * Gets the block involved in this event.
+     * @return the block
+     */
+    @NotNull
+    public Block getBlock() {
+        return block;
+    }
+
+    /**
+     * Gets if the block would appear to open, if this event is not cancelled.
+     * return if the block would appear to open
+     */
+    public boolean isOpening() {
+        return blockState.getLidMode() == LidMode.DEFAULT && blockState.getTrueLidState() == LidState.CLOSED;
+    }
+
+    @Override
+    @NotNull
+    public HandlerList getHandlers() {
+        return HANDLER_LIST;
+    }
+
+    public static @NotNull HandlerList getHandlerList() {
+        return HANDLER_LIST;
+    }
+}

paper-api/src/main/java/org/bukkit/block/Barrel.java

@@ -5,4 +5,4 @@
 /**
  * Represents a captured state of a Barrel.
  */
-public interface Barrel extends Container, com.destroystokyo.paper.loottable.LootableBlockInventory, Lidded { } // Paper
+public interface Barrel extends Container, com.destroystokyo.paper.loottable.LootableBlockInventory, Lidded, io.papermc.paper.block.Lidded { } // Paper

paper-api/src/main/java/org/bukkit/block/Chest.java

@@ -9,7 +9,7 @@
 /**
  * Represents a captured state of a chest.
  */
-public interface Chest extends Container, LootableBlockInventory, Lidded { // Paper
+public interface Chest extends Container, LootableBlockInventory, Lidded, io.papermc.paper.block.Lidded { // Paper
 
     /**
      * Gets the inventory of the chest block represented by this block state.

paper-api/src/main/java/org/bukkit/block/EnderChest.java

@@ -3,7 +3,7 @@
 /**
  * Represents a captured state of an ender chest.
  */
-public interface EnderChest extends Lidded, TileState {
+public interface EnderChest extends Lidded, TileState, io.papermc.paper.block.Lidded {
     // Paper start - More Chest Block API
     /**
      * Checks whether this ender chest is blocked by a block above

paper-api/src/main/java/org/bukkit/block/Lidded.java

@@ -1,25 +1,36 @@
 package org.bukkit.block;
 
+import io.papermc.paper.block.LidMode;
+
+/**
+ * @deprecated Incomplete api. Use {@link io.papermc.paper.block.Lidded} instead.
+ */
+@Deprecated // Paper - Deprecate Bukkit's Lidded API
 public interface Lidded {
 
     /**
      * Sets the block's animated state to open and prevents it from being closed
      * until {@link #close()} is called.
+     * @deprecated Use {@link io.papermc.paper.block.Lidded#setLidMode(LidMode)}
      */
+    @Deprecated
     void open();
 
     /**
-     * Sets the block's animated state to closed even if a player is currently
-     * viewing this block.
+     * Unsets a corresponding call to {@link #open()}.
+     * @deprecated Misleading name. Use {@link io.papermc.paper.block.Lidded#setLidMode(LidMode)}
      */
+    @Deprecated
     void close();
 
     // Paper start - More Lidded Block API
     /**
-     * Checks if the block's animation state.
+     * Checks is the Lid is currently forced open.
      *
-     * @return true if the block's animation state is set to open.
+     * @return true if the block's animation state is force open.
+     * @deprecated Misleading name. Use {@link io.papermc.paper.block.Lidded#getLidMode()} for the direct replacement, or {@link io.papermc.paper.block.Lidded#getEffectiveLidState()} to tell if the lid is visibly open to the player instead.
      */
+    @Deprecated
     boolean isOpen();
     // Paper end - More Lidded Block API
 }

paper-api/src/main/java/org/bukkit/block/ShulkerBox.java

@@ -8,7 +8,7 @@
 /**
  * Represents a captured state of a ShulkerBox.
  */
-public interface ShulkerBox extends Container, LootableBlockInventory, Lidded { // Paper
+public interface ShulkerBox extends Container, LootableBlockInventory, Lidded, io.papermc.paper.block.Lidded { // Paper
 
     /**
      * Get the {@link DyeColor} corresponding to this ShulkerBox