Active Item API

src/main/java/ch/njol/skript/classes/data/BukkitEventValues.java

@@ -37,12 +37,14 @@
 import ch.njol.skript.util.Direction;
 import ch.njol.skript.util.EnchantmentType;
 import ch.njol.skript.util.Getter;
+import ch.njol.skript.util.Timespan;
 import ch.njol.skript.util.slot.InventorySlot;
 import ch.njol.skript.util.slot.Slot;
 import com.destroystokyo.paper.event.block.AnvilDamagedEvent;
 import com.destroystokyo.paper.event.entity.ProjectileCollideEvent;
 import com.destroystokyo.paper.event.player.PlayerArmorChangeEvent;
 import io.papermc.paper.event.entity.EntityMoveEvent;
+import io.papermc.paper.event.player.PlayerStopUsingItemEvent;
 import io.papermc.paper.event.player.PlayerInventorySlotChangeEvent;
 import io.papermc.paper.event.player.PlayerStonecutterRecipeSelectEvent;
 import io.papermc.paper.event.player.PlayerTradeEvent;
@@ -1675,6 +1677,22 @@ public Egg get(PlayerEggThrowEvent event) {
 			}
 		}, EventValues.TIME_NOW);
 
+		// PlayerStopUsingItemEvent
+		if (Skript.classExists("io.papermc.paper.event.player.PlayerStopUsingItemEvent")) {
+			EventValues.registerEventValue(PlayerStopUsingItemEvent.class, Timespan.class, new Getter<Timespan, PlayerStopUsingItemEvent>() {
+				@Override
+				public Timespan get(PlayerStopUsingItemEvent event) {
+					return Timespan.fromTicks(event.getTicksHeldFor());
+				}
+			}, EventValues.TIME_NOW);
+			EventValues.registerEventValue(PlayerStopUsingItemEvent.class, ItemType.class, new Getter<ItemType, PlayerStopUsingItemEvent>() {
+				@Override
+				public ItemType get(PlayerStopUsingItemEvent event) {
+					return new ItemType(event.getItem());
+				}
+			}, EventValues.TIME_NOW);
+		}
+
 		// LootGenerateEvent
 		if (Skript.classExists("org.bukkit.event.world.LootGenerateEvent")) {
 			EventValues.registerEventValue(LootGenerateEvent.class, Entity.class, new Getter<Entity, LootGenerateEvent>() {

src/main/java/ch/njol/skript/conditions/CondIsHandRaised.java

@@ -0,0 +1,97 @@
+/**
+ *   This file is part of Skript.
+ *
+ *  Skript is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  Skript is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with Skript.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * Copyright Peter Güttinger, SkriptLang team and contributors
+ */
+package ch.njol.skript.conditions;
+
+import ch.njol.skript.Skript;
+import ch.njol.skript.doc.Description;
+import ch.njol.skript.doc.Examples;
+import ch.njol.skript.doc.Name;
+import ch.njol.skript.doc.RequiredPlugins;
+import ch.njol.skript.doc.Since;
+import ch.njol.skript.lang.Condition;
+import ch.njol.skript.lang.Expression;
+import ch.njol.skript.lang.SkriptParser.ParseResult;
+import ch.njol.util.Kleenean;
+import org.bukkit.entity.LivingEntity;
+import org.bukkit.event.Event;
+import org.bukkit.inventory.EquipmentSlot;
+import org.eclipse.jdt.annotation.Nullable;
+
+@Name("Is Hand Raised")
+@Description({
+	"Checks whether an entity has one or both of their hands raised.",
+	"Hands are raised when an entity is using an item (eg: blocking, drawing a bow, eating)."
+})
+@Examples({
+	"on damage of player:",
+		"\tif victim's main hand is raised:",
+			"\t\tdrop player's tool at player",
+			"\t\tset player's tool to air"
+})
+@Since("INSERT VERSION")
+@RequiredPlugins("Paper")
+public class CondIsHandRaised extends Condition {
+
+	static {
+		Skript.registerCondition(CondIsHandRaised.class,
+				"%livingentities%'[s] [:main] hand[s] (is|are) raised",
+				"%livingentities%'[s] [:main] hand[s] (isn't|is not|aren't|are not) raised",
+				"[:main] hand[s] of %livingentities% (is|are) raised",
+				"[:main] hand[s] of %livingentities% (isn't|is not|aren't|are not) raised",
+
+				"%livingentities%'[s] off[ |-]hand[s] (is|are) raised",
+				"%livingentities%'[s] off[ |-]hand[s] (isn't|is not|aren't|are not) raised",
+				"off[ |-]hand[s] of %livingentities% (is|are) raised",
+				"off[ |-]hand[s] of %livingentities% (isn't|is not|aren't|are not) raised"
+		);
+	}
+
+	private Expression<LivingEntity> entities;
+	@Nullable
+	private EquipmentSlot hand;
+
+	@Override
+	@SuppressWarnings("unchecked")
+	public boolean init(Expression<?>[] exprs, int matchedPattern, Kleenean isDelayed, ParseResult parseResult) {
+		entities = (Expression<LivingEntity>) exprs[0];
+		setNegated(matchedPattern % 2 == 1);
+		if (matchedPattern >= 4) {
+			hand = EquipmentSlot.OFF_HAND;
+		} else if (parseResult.hasTag("main")) {
+			hand = EquipmentSlot.HAND;
+		}
+		return true;
+	}
+
+	@Override
+	public boolean check(Event event) {
+		// True if hand is raised AND hand matches the hand we're checking for (null for both)
+		return entities.check(event, livingEntity ->
+				livingEntity.isHandRaised() && ((hand == null) || livingEntity.getHandRaised().equals(hand)),
+				isNegated()
+		);
+	}
+
+	@Override
+	public String toString(@Nullable Event event, boolean debug) {
+		return entities.toString(event, debug) + "'s  " + (hand == null ? "" : (hand == EquipmentSlot.HAND ? "main " : "off ")) + "hand" +
+				(entities.isSingle() ? " is" : "s are") + (isNegated() ? " not " : "") + " raised";
+	}
+
+}

src/main/java/ch/njol/skript/effects/EffCancelItemUse.java

@@ -0,0 +1,77 @@
+/**
+ *   This file is part of Skript.
+ *
+ *  Skript is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  Skript is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with Skript.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * Copyright Peter Güttinger, SkriptLang team and contributors
+ */
+package ch.njol.skript.effects;
+
+import ch.njol.skript.Skript;
+import ch.njol.skript.doc.Description;
+import ch.njol.skript.doc.Examples;
+import ch.njol.skript.doc.Name;
+import ch.njol.skript.doc.RequiredPlugins;
+import ch.njol.skript.doc.Since;
+import ch.njol.skript.lang.Effect;
+import ch.njol.skript.lang.Expression;
+import ch.njol.skript.lang.SkriptParser.ParseResult;
+import ch.njol.util.Kleenean;
+import org.bukkit.entity.LivingEntity;
+import org.bukkit.event.Event;
+import org.eclipse.jdt.annotation.Nullable;
+
+@Name("Cancel Active Item")
+@Description({
+	"Interrupts the action entities may be trying to complete.",
+	"For example, interrupting eating, or drawing back a bow."
+})
+@Examples({
+	"on damage of player:",
+		"\tif the victim's active tool is a bow:",
+			"\t\tinterrupt the usage of the player's active item"
+})
+@Since("INSERT VERSION")
+@RequiredPlugins("Paper 1.16+")
+public class EffCancelItemUse extends Effect {
+
+	static {
+		if (Skript.methodExists(LivingEntity.class, "clearActiveItem"))
+			Skript.registerEffect(EffCancelItemUse.class,
+					"(cancel|interrupt) [the] us[ag]e of %livingentities%'[s] [active|current] item"
+			);
+	}
+
+	private Expression<LivingEntity> entities;
+
+	@Override
+	@SuppressWarnings("unchecked")
+	public boolean init(Expression<?>[] exprs, int matchedPattern, Kleenean isDelayed, ParseResult parseResult) {
+		entities = (Expression<LivingEntity>) exprs[0];
+		return true;
+	}
+
+	@Override
+	protected void execute(Event event) {
+		for (LivingEntity entity : entities.getArray(event)) {
+			entity.clearActiveItem();
+		}
+	}
+
+	@Override
+	public String toString(@Nullable Event event, boolean debug) {
+		return "cancel the usage of " + entities.toString(event, debug) + "'s active item";
+	}
+
+}

src/main/java/ch/njol/skript/events/SimpleEvents.java

@@ -19,6 +19,8 @@
 package ch.njol.skript.events;
 
 import com.destroystokyo.paper.event.block.AnvilDamagedEvent;
+import com.destroystokyo.paper.event.player.PlayerReadyArrowEvent;
+import io.papermc.paper.event.player.PlayerStopUsingItemEvent;
 import io.papermc.paper.event.player.PlayerDeepSleepEvent;
 import io.papermc.paper.event.player.PlayerInventorySlotChangeEvent;
 import org.bukkit.event.block.BlockCanBuildEvent;
@@ -654,17 +656,47 @@ public class SimpleEvents {
 					"\tcancel the event")
 				.since("2.7");
 		}
+
+		if (Skript.classExists("io.papermc.paper.event.player.PlayerStopUsingItemEvent")) {
+			Skript.registerEvent("Stop Using Item", SimpleEvent.class, PlayerStopUsingItemEvent.class,
+							"[player] (stop|end) (using item|item use)")
+					.description("Called when a player stops using an item. For example, when the player releases the " +
+							"interact button when holding a bow, an edible item, or a spyglass.",
+							"Note that event-timespan will return the time the item was used for.")
+					.requiredPlugins("Paper 1.18.2+")
+					.examples(
+						"on player stop using item:",
+							"\tbroadcast \"%player% used %event-item% for %event-timespan%.\"")
+					.since("INSERT VERSION");
+		}
+
+		if (Skript.classExists("com.destroystokyo.paper.event.player.PlayerReadyArrowEvent")) {
+			Skript.registerEvent("Ready Arrow", SimpleEvent.class, PlayerReadyArrowEvent.class, "[player] ((ready|choose|draw|load) arrow|arrow (choose|draw|load))")
+					.description("Called when a player is firing a bow and the server is choosing an arrow to use.",
+							"Cancelling this event will skip the current arrow item and fire a new event for the next arrow item.",
+							"The arrow and bow in the event can be accessed with the Readied Arrow/Bow expression.")
+					.requiredPlugins("Paper")
+					.examples(
+						"on player ready arrow:",
+							"\tselected bow's name is \"Spectral Bow\"",
+							"\tif selected arrow is not a spectral arrow:",
+								"\t\tcancel event"
+					)
+					.since("INSERT VERSION");
+		}
+
 		if (Skript.classExists("io.papermc.paper.event.player.PlayerInventorySlotChangeEvent")) {
 			Skript.registerEvent("Inventory Slot Change", SimpleEvent.class, PlayerInventorySlotChangeEvent.class, "[player] inventory slot chang(e|ing)")
-				.description("Called when a slot in a player's inventory is changed.", "Warning: setting the event-slot to a new item can result in an infinite loop.")
-				.requiredPlugins("Paper 1.19.2+")
-				.examples(
-					"on inventory slot change:",
-						"\tif event-item is a diamond:",
-							"\t\tsend \"You obtained a diamond!\" to player"
-				)
-				.since("2.7");
+					.description("Called when a slot in a player's inventory is changed.", "Warning: setting the event-slot to a new item can result in an infinite loop.")
+					.requiredPlugins("Paper 1.19.2+")
+					.examples(
+						"on inventory slot change:",
+							"\tif event-item is a diamond:",
+								"\t\tsend \"You obtained a diamond!\" to player"
+					)
+					.since("2.7");
 		}
+
 		//noinspection deprecation
 		Skript.registerEvent("Chat", SimpleEvent.class, AsyncPlayerChatEvent.class, "chat")
 			.description(

src/main/java/ch/njol/skript/expressions/ExprActiveItem.java

@@ -0,0 +1,70 @@
+/**
+ *   This file is part of Skript.
+ *
+ *  Skript is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  Skript is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with Skript.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * Copyright Peter Güttinger, SkriptLang team and contributors
+ */
+package ch.njol.skript.expressions;
+
+import ch.njol.skript.Skript;
+import ch.njol.skript.doc.Description;
+import ch.njol.skript.doc.Examples;
+import ch.njol.skript.doc.Name;
+import ch.njol.skript.doc.RequiredPlugins;
+import ch.njol.skript.doc.Since;
+import ch.njol.skript.expressions.base.SimplePropertyExpression;
+import org.bukkit.Material;
+import org.bukkit.entity.LivingEntity;
+import org.bukkit.inventory.ItemStack;
+import org.eclipse.jdt.annotation.Nullable;
+
+@Name("Active Item")
+@Description(
+	"Returns the item the entities are currently using (ie: the food they're eating, " +
+	"the bow they're drawing back, etc.). This cannot be changed. " +
+	"If an entity is not using any item, this will return null."
+)
+@Examples({
+	"on damage of player:",
+		"\tif victim's active tool is a bow:",
+			"\t\tinterrupt player's active item use"
+})
+@Since("INSERT VERSION")
+@RequiredPlugins("Paper")
+public class ExprActiveItem extends SimplePropertyExpression<LivingEntity, ItemStack> {
+
+	static {
+		if (Skript.methodExists(LivingEntity.class, "getActiveItem"))
+			register(ExprActiveItem.class, ItemStack.class, "(raised|active) (tool|item|weapon)", "livingentities");
+	}
+
+	@Override
+	@Nullable
+	public ItemStack convert(LivingEntity livingEntity) {
+		ItemStack item = livingEntity.getActiveItem();
+		return item.getType() == Material.AIR ? null : item;
+	}
+
+	@Override
+	public Class<? extends ItemStack> getReturnType() {
+		return ItemStack.class;
+	}
+
+	@Override
+	protected String getPropertyName() {
+		return "active item";
+	}
+
+}