feature: expose mannequin poses and provide pose argument

yannicklamprecht · yannicklamprecht · commit dcf63d12916e · 2025-12-23T22:23:13.000+01:00
diff --git a/paper-api/src/main/java/io/papermc/paper/InternalAPIBridge.java b/paper-api/src/main/java/io/papermc/paper/InternalAPIBridge.java
@@ -5,6 +5,7 @@
 import io.papermc.paper.datacomponent.item.ResolvableProfile;
 import io.papermc.paper.world.damagesource.CombatEntry;
 import io.papermc.paper.world.damagesource.FallLocationType;
+import java.util.Set;
 import java.util.function.Function;
 import java.util.function.Predicate;
 import net.kyori.adventure.text.Component;
@@ -14,6 +15,7 @@
 import org.bukkit.damage.DamageEffect;
 import org.bukkit.damage.DamageSource;
 import org.bukkit.entity.LivingEntity;
+import org.bukkit.entity.Pose;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Contract;
 import org.jspecify.annotations.NullMarked;
@@ -100,4 +102,6 @@ class Holder {
     Component defaultMannequinDescription();
 
     <MODERN, LEGACY> GameRule<LEGACY> legacyGameRuleBridge(GameRule<MODERN> rule, Function<LEGACY, MODERN> fromLegacyToModern, Function<MODERN, LEGACY> toLegacyFromModern, Class<LEGACY> legacyClass);
+
+    Set<Pose> validMannequinPoses();
 }
diff --git a/paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/ArgumentTypes.java b/paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/ArgumentTypes.java
@@ -32,6 +32,7 @@
 import org.bukkit.block.BlockState;
 import org.bukkit.block.structure.Mirror;
 import org.bukkit.block.structure.StructureRotation;
+import org.bukkit.entity.Pose;
 import org.bukkit.inventory.ItemStack;
 import org.bukkit.scoreboard.Criteria;
 import org.bukkit.scoreboard.DisplaySlot;
@@ -452,6 +453,26 @@ public static <T> ArgumentType<TypedKey<T>> resourceKey(final RegistryKey<T> reg
         return provider().resourceKey(registryKey);
     }
 
+    /**
+     * An argument for getting a pose
+     * Keep in mind that a mannequin has only a subset of poses.
+     * Use {@link #mannequin()} for mannequin-specific poses.
+     *
+     * @return argument
+     */
+    public static ArgumentType<Pose> pose() {
+        return provider().pose();
+    }
+
+    /**
+     * An argument for getting a mannequin-specific pose
+     *
+     * @return argument
+     */
+    public static ArgumentType<Pose> mannequin() {
+        return provider().mannequin();
+    }
+
     private ArgumentTypes() {
     }
 }
diff --git a/paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/VanillaArgumentProvider.java b/paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/VanillaArgumentProvider.java
@@ -32,6 +32,7 @@
 import org.bukkit.block.BlockState;
 import org.bukkit.block.structure.Mirror;
 import org.bukkit.block.structure.StructureRotation;
+import org.bukkit.entity.Pose;
 import org.bukkit.inventory.ItemStack;
 import org.bukkit.scoreboard.Criteria;
 import org.bukkit.scoreboard.DisplaySlot;
@@ -120,4 +121,8 @@ static VanillaArgumentProvider provider() {
     <T> ArgumentType<TypedKey<T>> resourceKey(RegistryKey<T> registryKey);
 
     <T> ArgumentType<T> resource(RegistryKey<T> registryKey);
+
+    ArgumentType<Pose> pose();
+
+    ArgumentType<Pose> mannequin();
 }
diff --git a/paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/pose/PoseArgument.java b/paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/pose/PoseArgument.java
@@ -0,0 +1,67 @@
+package io.papermc.paper.command.brigadier.argument.pose;
+
+import com.mojang.brigadier.arguments.ArgumentType;
+import com.mojang.brigadier.arguments.StringArgumentType;
+import com.mojang.brigadier.context.CommandContext;
+import com.mojang.brigadier.exceptions.CommandSyntaxException;
+import com.mojang.brigadier.exceptions.DynamicCommandExceptionType;
+import com.mojang.brigadier.suggestion.Suggestions;
+import com.mojang.brigadier.suggestion.SuggestionsBuilder;
+import io.papermc.paper.command.brigadier.MessageComponentSerializer;
+import io.papermc.paper.command.brigadier.argument.CustomArgumentType;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.Locale;
+import java.util.Set;
+import java.util.concurrent.CompletableFuture;
+import net.kyori.adventure.text.Component;
+import org.bukkit.entity.Mannequin;
+import org.bukkit.entity.Pose;
+
+public class PoseArgument implements CustomArgumentType.Converted<Pose, String> {
+
+    private final Set<Pose> validPoses;
+
+    private PoseArgument(final Set<Pose> poses) {
+        validPoses = poses;
+    }
+
+    public static PoseArgument pose() {
+        return new PoseArgument(new HashSet<>(Arrays.asList(Pose.values())));
+    }
+
+    public static PoseArgument mannequin() {
+        return new PoseArgument(Mannequin.validPoses());
+    }
+
+    private static final DynamicCommandExceptionType ERROR_INVALID = new DynamicCommandExceptionType(value -> {
+        return MessageComponentSerializer.message().serialize(Component.text(value + " is not a valid pose!"));
+    });
+
+    @Override
+    public ArgumentType<String> getNativeType() {
+        return StringArgumentType.word();
+    }
+
+    @Override
+    public Pose convert(String nativeType) throws CommandSyntaxException {
+        try {
+            return Pose.valueOf(nativeType.toUpperCase(Locale.ROOT));
+        } catch (IllegalArgumentException ignored) {
+            throw ERROR_INVALID.create(nativeType);
+        }
+    }
+
+    @Override
+    public <S> CompletableFuture<Suggestions> listSuggestions(CommandContext<S> context, SuggestionsBuilder builder) {
+        for (Pose pose : this.validPoses) {
+            String name = pose.toString().toLowerCase(Locale.ROOT);
+
+            if (name.startsWith(builder.getRemainingLowerCase())) {
+                builder.suggest(pose.toString());
+            }
+        }
+
+        return builder.buildFuture();
+    }
+}
diff --git a/paper-api/src/main/java/org/bukkit/entity/Mannequin.java b/paper-api/src/main/java/org/bukkit/entity/Mannequin.java
@@ -3,6 +3,7 @@
 import com.destroystokyo.paper.SkinParts;
 import io.papermc.paper.InternalAPIBridge;
 import io.papermc.paper.datacomponent.item.ResolvableProfile;
+import java.util.Set;
 import net.kyori.adventure.text.Component;
 import org.bukkit.inventory.EntityEquipment;
 import org.bukkit.inventory.MainHand;
@@ -12,6 +13,15 @@
 @NullMarked
 public interface Mannequin extends LivingEntity {
 
+    /**
+     * Returns the valid poses for a mannequin.
+     *
+     * @return the valid poses
+     */
+    static Set<Pose> validPoses() {
+        return InternalAPIBridge.get().validMannequinPoses();
+    }
+
     /**
      * Returns the default mannequin profile.
      *
diff --git a/paper-server/src/main/java/io/papermc/paper/PaperServerInternalAPIBridge.java b/paper-server/src/main/java/io/papermc/paper/PaperServerInternalAPIBridge.java
@@ -10,8 +10,10 @@
 import io.papermc.paper.world.damagesource.FallLocationType;
 import io.papermc.paper.world.damagesource.PaperCombatEntryWrapper;
 import io.papermc.paper.world.damagesource.PaperCombatTrackerWrapper;
+import java.util.Set;
 import java.util.function.Function;
 import java.util.function.Predicate;
+import java.util.stream.Collectors;
 import net.kyori.adventure.text.Component;
 import net.minecraft.Optionull;
 import net.minecraft.commands.Commands;
@@ -27,13 +29,17 @@
 import org.bukkit.damage.DamageEffect;
 import org.bukkit.damage.DamageSource;
 import org.bukkit.entity.LivingEntity;
+import org.bukkit.entity.Pose;
 import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 @NullMarked
 public class PaperServerInternalAPIBridge implements InternalAPIBridge {
     public static final PaperServerInternalAPIBridge INSTANCE = new PaperServerInternalAPIBridge();
 
+    private static final Set<Pose> validMannequinPoses = Mannequin.VALID_POSES.stream()
+        .map(pose -> Pose.values()[pose.ordinal()]).collect(Collectors.toSet());
+
     @Override
     public DamageEffect getDamageEffect(final String key) {
         return CraftDamageEffect.getById(key);
@@ -116,4 +122,9 @@ public Component defaultMannequinDescription() {
     public <MODERN, LEGACY> GameRule<LEGACY> legacyGameRuleBridge(GameRule<MODERN> rule, Function<LEGACY, MODERN> fromLegacyToModern, Function<MODERN, LEGACY> toLegacyFromModern, Class<LEGACY> legacyClass) {
         return CraftGameRule.wrap(rule, fromLegacyToModern, toLegacyFromModern, legacyClass);
     }
+
+    @Override
+    public Set<Pose> validMannequinPoses() {
+        return validMannequinPoses;
+    }
 }
diff --git a/paper-server/src/main/java/io/papermc/paper/command/brigadier/argument/VanillaArgumentProviderImpl.java b/paper-server/src/main/java/io/papermc/paper/command/brigadier/argument/VanillaArgumentProviderImpl.java
@@ -13,6 +13,7 @@
 import com.mojang.brigadier.suggestion.SuggestionsBuilder;
 import io.papermc.paper.adventure.PaperAdventure;
 import io.papermc.paper.command.brigadier.PaperCommands;
+import io.papermc.paper.command.brigadier.argument.pose.PoseArgument;
 import io.papermc.paper.command.brigadier.argument.predicate.BlockInWorldPredicate;
 import io.papermc.paper.command.brigadier.argument.predicate.ItemStackPredicate;
 import io.papermc.paper.command.brigadier.argument.range.DoubleRangeProvider;
@@ -114,6 +115,7 @@
 import org.bukkit.craftbukkit.scoreboard.CraftScoreboardTranslations;
 import org.bukkit.craftbukkit.util.CraftLocation;
 import org.bukkit.craftbukkit.util.CraftNamespacedKey;
+import org.bukkit.entity.Pose;
 import org.bukkit.inventory.ItemStack;
 import org.bukkit.scoreboard.Criteria;
 import org.bukkit.scoreboard.DisplaySlot;
@@ -416,6 +418,16 @@ public <T> ArgumentType<T> resource(final RegistryKey<T> registryKey) {
         return this.resourceRaw(registryKey);
     }
 
+    @Override
+    public ArgumentType<Pose> pose() {
+        return PoseArgument.pose();
+    }
+
+    @Override
+    public ArgumentType<Pose> mannequin() {
+        return PoseArgument.mannequin();
+    }
+
     @SuppressWarnings({"unchecked", "rawtypes", "UnnecessaryLocalVariable"})
     private <T, K extends Keyed> ArgumentType<T> resourceRaw(final RegistryKey registryKeyRaw) { // TODO remove Keyed
         final RegistryKey<K> registryKey = registryKeyRaw;
diff --git a/paper-server/src/main/java/org/bukkit/craftbukkit/entity/CraftMannequin.java b/paper-server/src/main/java/org/bukkit/craftbukkit/entity/CraftMannequin.java
@@ -31,15 +31,14 @@ public net.minecraft.world.entity.decoration.Mannequin getHandle() {
     @Override
     public void setPose(Pose pose, boolean fixed) {
         Preconditions.checkArgument(pose != null, "pose cannot be null");
-        net.minecraft.world.entity.Pose internalPose = net.minecraft.world.entity.Pose.values()[pose.ordinal()];
-        if (!net.minecraft.world.entity.decoration.Mannequin.VALID_POSES.contains(internalPose)) {
+        if (!Mannequin.validPoses().contains(pose)) {
             throw new IllegalArgumentException("Invalid pose '%s', expected one of: %s".formatted(
                 pose.name(),
-                net.minecraft.world.entity.decoration.Mannequin.VALID_POSES.stream().map(p -> Pose.values()[p.ordinal()]).toList() // name doesn't match
+                Mannequin.validPoses().stream().toList() // name doesn't match
             ));
         }
 
-        this.setPose0(internalPose, fixed);
+        this.setPose0(net.minecraft.world.entity.Pose.values()[pose.ordinal()], fixed);
     }
 
     @Override
