贺兰兰
聊聊 PaperAPI 提供的自定义生物 AI 系统

本文也发表于我的博客: https://my.minecraft.kim/tech/2021/12/19/post-393/

灵感：https://www.mcbbs.net/thread-1285618-1-1.html（原文发布于 https://izzel.io/2021/12/19/living-things）

本文旨在介绍由 PaperAPI 封装的自定义生物行为（AI）系统（com.destroystokyo.paper.entity.ai），籍由此系统，我们可以在不接触 NMS 的情况下为单个生物自定义其 AI。本文代码基于 Paper-API 1.16.5。

阅读本文可能需要了解原版的生物 AI 机制，如果您不了解这些机制，则可以阅读海螺的 聊聊生物和 AI 文章（即本文灵感）来对这些机制有一些初步的了解

摒弃 NMS

众所周知，与 Forge 不同，Bukkit API 总是希望包揽一切，提供一套稳定的，高度封装的 API 给服务端插件开发者，而不希望开发者基于内部代码进行开发。但因为各种原因，原生 Bukkit API（甚至 Spigot API）提供的封装总是有限，对于一些进阶的操作，我们总是需要访问和调用内部代码来实现我们所需要的操作。自定义生物 AI 就是其中的一个：以往，开发者们往往需要自行继承原来的生物实体类，然后重载 Goal 初始化方法，甚至利用反射来添加，或是擦除生物 AI——但有了 Paper API 后，这一切都会变得简单，且可控。

了解 PaprAPI 封装的自定义生物 AI 系统

大致来看，PaperAPI 封装的自定义生物 AI 系统主要由 Goal<T extends Mob> 和 MobGoals 两部分组成

先来看 Goal 类的构造：

  1. package com.destroystokyo.paper.entity.ai;

  3. import org.jetbrains.annotations.NotNull;

  5. import java.util.EnumSet;

  7. import org.bukkit.entity.Mob;

  9. /**
  10. * Represents an AI goal of an entity
  11. */
  12. public interface Goal<T extends Mob> {

  14.     /**
  15.      * Checks if this goal should be activated
  16.      *
  17.      * [url=home.php?mod=space&uid=491268]@Return[/url] if this goal should be activated
  18.      */
  19.     boolean shouldActivate();

  21.     /**
  22.      * Checks if this goal should stay active, defaults to {[url=home.php?mod=space&uid=41191]@link[/url] Goal#shouldActivate()}
  23.      *
  24.      * @return if this goal should stay active
  25.      */
  26.     default boolean shouldStayActive() {
  27.         return shouldActivate();
  28.     }

  30.     /**
  31.      * Called when this goal gets activated
  32.      */
  33.     default void start() {
  34.     }

  36.     /**
  37.      * Called when this goal gets stopped
  38.      */
  39.     default void stop() {
  40.     }

  42.     /**
  43.      * Called each tick the goal is activated
  44.      */
  45.     default void tick() {
  46.     }

  48.     /**
  49.      * A unique key that identifies this type of goal. Plugins should use their own namespace, not the minecraft
  50.      * namespace. Additionally, this key also specifies to what mobs this goal can be applied to
  51.      *
  52.      * @return the goal key
  53.      */
  54.     @NotNull
  55.     GoalKey<T> getKey();

  57.     /**
  58.      * Returns a list of all applicable flags for this goal.<br>
  59.      *
  60.      * This method is only called on construction.
  61.      *
  62.      * @return the subtypes.
  63.      */
  64.     @NotNull
  65.     EnumSet<GoalType> getTypes();
  66. }
复制代码

如果接触过 Minecraft 原版 Goal 的开发者，相信已经八九不离十的知道这是什么东西了 —— 其作用，甚至结构都和 Goal 差不多，即用于描述生物的一种行为。在这其中，GoalType：

  1. package com.destroystokyo.paper.entity.ai;

  3. /**
  4. * Represents the subtype of a goal. Used by minecraft to disable certain types of goals if needed.
  5. */
  6. public enum GoalType {

  8.     MOVE,
  9.     LOOK,
  10.     JUMP,
  11.     TARGET,
  12.     /**
  13.      * Used to map vanilla goals, that are a behavior goal but don't have a type set...
  14.      */
  15.     UNKNOWN_BEHAVIOR,

  17. }
复制代码

和原版的 Goal.Flag 也大差不差，除了多了一个 UNKNOWN_BEHAVIOR 枚举用于映射 Vanilla 的 Goal。

但细心的人也许会发现，Paper API 的 Goal 和原版的 Goal 还是有一些不同：Paper API 的 Goal 是一个泛型接口，同时额外要求实现一个 GoalKey<T> getKey() 方法。

当我们查看 GoalKey<T extends Mob> 的主要部分，我们立即就能明白其作用：

  1. package com.destroystokyo.paper.entity.ai;

  3. import com.google.common.base.Objects;

  5. import org.jetbrains.annotations.NotNull;

  7. import java.util.StringJoiner;

  9. import org.bukkit.NamespacedKey;
  10. import org.bukkit.entity.Mob;

  12. /**
  13. *
  14. * Used to identify a Goal. Consists of a {@link NamespacedKey} and the type of mob the goal can be applied to
  15. *
  16. * @param <T> the type of mob the goal can be applied to
  17. */
  18. public class GoalKey<T extends Mob> {

  20.     private final Class<T> entityClass;
  21.     private final NamespacedKey namespacedKey;

  23.     private GoalKey(@NotNull Class<T> entityClass, @NotNull NamespacedKey namespacedKey) {
  24.         this.entityClass = entityClass;
  25.         this.namespacedKey = namespacedKey;
  26.     }

  28.     // Omit getter, equals, hashcode and toString methods...

  30.     @NotNull
  31.     public static <A extends Mob> GoalKey<A> of(@NotNull Class<A> entityClass, @NotNull NamespacedKey namespacedKey) {
  32.         return new GoalKey<>(entityClass, namespacedKey);
  33.     }
  34. }
复制代码

它存在的作用就是为了作唯一标识符标识单个 Goal，同时配合 Goal 使用泛型约束这个 Goal 可以被应用到的生物类型。

那么如此以来，我们便摸透了 Goal 的内容，可以开始编写我们自己的自定义 AI了，但是...如何将这些 Goal 应用到我们的生物上呢？这时就需要介绍 ModGoals  了：

  1. package com.destroystokyo.paper.entity.ai;

  3. import org.jetbrains.annotations.NotNull;
  4. import org.jetbrains.annotations.Nullable;

  6. import java.util.Collection;

  8. import org.bukkit.entity.Mob;

  10. /**
  11. * Represents a part of the "brain" of a mob. It tracks all tasks (running or not), allows adding and removing goals
  12. */
  13. public interface MobGoals {

  15.     <T extends Mob> void addGoal(@NotNull T mob, int priority, @NotNull Goal<T> goal);

  17.     <T extends Mob> void removeGoal(@NotNull T mob, @NotNull Goal<T> goal);

  19.     <T extends Mob> void removeAllGoals(@NotNull T mob);

  21.     <T extends Mob> void removeAllGoals(@NotNull T mob, @NotNull GoalType type);

  23.     <T extends Mob> void removeGoal(@NotNull T mob, @NotNull GoalKey<T> key);

  25.     <T extends Mob> boolean hasGoal(@NotNull T mob, @NotNull GoalKey<T> key);

  27.     @Nullable
  28.     <T extends Mob> Goal<T> getGoal(@NotNull T mob, @NotNull GoalKey<T> key);

  30.     @NotNull
  31.     <T extends Mob> Collection<Goal<T>> getGoals(@NotNull T mob, @NotNull GoalKey<T> key);

  33.     @NotNull
  34.     <T extends Mob> Collection<Goal<T>> getAllGoals(@NotNull T mob);

  36.     @NotNull
  37.     <T extends Mob> Collection<Goal<T>> getAllGoals(@NotNull T mob, @NotNull GoalType type);

  39.     @NotNull
  40.     <T extends Mob> Collection<Goal<T>> getAllGoalsWithout(@NotNull T mob, @NotNull GoalType type);

  42.     @NotNull
  43.     <T extends Mob> Collection<Goal<T>> getRunningGoals(@NotNull T mob);

  45.     @NotNull
  46.     <T extends Mob> Collection<Goal<T>> getRunningGoals(@NotNull T mob, @NotNull GoalType type);

  48.     @NotNull
  49.     <T extends Mob> Collection<Goal<T>> getRunningGoalsWithout(@NotNull T mob, @NotNull GoalType type);
  50. }
复制代码

看完代码我们就会明白，这个所谓的 MobGoals 其实就是一个 Manager，用来方便的为生物获取、添加和删除 Goal，至于这些方法的作用，相信我不用说大家也都知道了。

最后，要想获取 MobGoals 实例，只需调用 Bukkit.getMobGoals() 方法（同 Bukkit.getServer().getMobGoals() 方法）即可。

当然，额外的，我们还可以配合 Pathfinder 和 PaperAPI 提供的其他 API 封装辅助开发自定义生物 AI，在这里对这些手段进行一些简单的介绍：

Pathfinder

即 com.destroystokyo.paper.entity.Pathfinder，可以通过 Mob#getPathfinder() 获取到 Pathfinder 实例。和他的名字一样，Pathfinder 就是一个生物的寻路器，PaperAPI 封装的 Pathfinder 为我们提供了像是 寻路、寻路并按此路径移动、设置生物是否可以开门、设置生物是否可以漂浮在水上 之类的便捷方法，令开发者便捷的使生物寻路和自定义移动行为

PaperAPI 提供的其他 API 封装辅助开发自定义生物 AI

除此之外，PaperAPI 还为我们提供了其他的一些便于辅助开发自定义生物 AI 的方法，例如 Mob#lookAt(@NotNull org.bukkit.Location location) 和 Mob#lookAt(@NotNull Entity entity) 就允许我们命令一个生物望向指定 Location 或指定 Enrtity。

使用 Minecraft 原生生物 AI —— VanillaGoal

但是，如果我想偷懒，希望使用 Minecraft 原生的生物 AI，而不是从零开始自己实现一个全新的 AI，该怎么做呢？

在 VanillaGoal<T extends Mob> 类中，我们可以看到其中已经预先声明了很多原版 Goal 对应的 GoalKey：

  1. package com.destroystokyo.paper.entity.ai;

  3. import com.destroystokyo.paper.entity.RangedEntity;

  5. import org.bukkit.NamespacedKey;
  6. import org.bukkit.entity.*;

  8. /**
  9. * Represents a vanilla goal. Plugins should never implement this.<br>
  10. * Generated by VanillaPathfinderTest in paper-server
  11. */
  12. public interface VanillaGoal<T extends Mob> extends Goal<T> {

  14.     GoalKey<Bee> BEE_ATTACK = GoalKey.of(Bee.class, NamespacedKey.minecraft("bee_attack"));
  15.     GoalKey<Bee> BEE_BECOME_ANGRY = GoalKey.of(Bee.class, NamespacedKey.minecraft("bee_become_angry"));
  16.     GoalKey<Bee> BEE_ENTER_HIVE = GoalKey.of(Bee.class, NamespacedKey.minecraft("bee_enter_hive"));
  17.     GoalKey<Bee> BEE_GO_TO_HIVE = GoalKey.of(Bee.class, NamespacedKey.minecraft("bee_go_to_hive"));
  18.     GoalKey<Bee> BEE_GO_TO_KNOWN_FLOWER = GoalKey.of(Bee.class, NamespacedKey.minecraft("bee_go_to_known_flower"));
  19.     GoalKey<Bee> BEE_GROW_CROP = GoalKey.of(Bee.class, NamespacedKey.minecraft("bee_grow_crop"));
  20.     GoalKey<Bee> BEE_HURT_BY_OTHER = GoalKey.of(Bee.class, NamespacedKey.minecraft("bee_hurt_by_other"));
  21.     GoalKey<Bee> BEE_LOCATE_HIVE = GoalKey.of(Bee.class, NamespacedKey.minecraft("bee_locate_hive"));
  22.     GoalKey<Bee> BEE_POLLINATE = GoalKey.of(Bee.class, NamespacedKey.minecraft("bee_pollinate"));
  23.     GoalKey<Bee> BEE_WANDER = GoalKey.of(Bee.class, NamespacedKey.minecraft("bee_wander"));
  24.     GoalKey<Blaze> BLAZE_FIREBALL = GoalKey.of(Blaze.class, NamespacedKey.minecraft("blaze_fireball"));
  25.     GoalKey<Cat> TEMPT_CHANCE = GoalKey.of(Cat.class, NamespacedKey.minecraft("tempt_chance"));
  26.     GoalKey<Cat> CAT_AVOID_ENTITY = GoalKey.of(Cat.class, NamespacedKey.minecraft("cat_avoid_entity"));
  27.     GoalKey<Cat> CAT_RELAX_ON_OWNER = GoalKey.of(Cat.class, NamespacedKey.minecraft("cat_relax_on_owner"));
  28.     GoalKey<Dolphin> DOLPHIN_SWIM_TO_TREASURE = GoalKey.of(Dolphin.class, NamespacedKey.minecraft("dolphin_swim_to_treasure"));
  29.     GoalKey<Dolphin> DOLPHIN_SWIM_WITH_PLAYER = GoalKey.of(Dolphin.class, NamespacedKey.minecraft("dolphin_swim_with_player"));
  30.     GoalKey<Dolphin> DOLPHIN_PLAY_WITH_ITEMS = GoalKey.of(Dolphin.class, NamespacedKey.minecraft("dolphin_play_with_items"));
  31.     GoalKey<Drowned> DROWNED_ATTACK = GoalKey.of(Drowned.class, NamespacedKey.minecraft("drowned_attack"));
  32.     GoalKey<Drowned> DROWNED_GOTO_BEACH = GoalKey.of(Drowned.class, NamespacedKey.minecraft("drowned_goto_beach"));
  33.     GoalKey<Creature> DROWNED_GOTO_WATER = GoalKey.of(Creature.class, NamespacedKey.minecraft("drowned_goto_water"));
  34.     GoalKey<Drowned> DROWNED_SWIM_UP = GoalKey.of(Drowned.class, NamespacedKey.minecraft("drowned_swim_up"));
  35.     GoalKey<RangedEntity> DROWNED_TRIDENT_ATTACK = GoalKey.of(RangedEntity.class, NamespacedKey.minecraft("drowned_trident_attack"));
  36.     GoalKey<Enderman> ENDERMAN_PICKUP_BLOCK = GoalKey.of(Enderman.class, NamespacedKey.minecraft("enderman_pickup_block"));
  37.     GoalKey<Enderman> ENDERMAN_PLACE_BLOCK = GoalKey.of(Enderman.class, NamespacedKey.minecraft("enderman_place_block"));
  38.     GoalKey<Enderman> PLAYER_WHO_LOOKED_AT_TARGET = GoalKey.of(Enderman.class, NamespacedKey.minecraft("player_who_looked_at_target"));
  39.     GoalKey<Enderman> ENDERMAN_FREEZE_WHEN_LOOKED_AT = GoalKey.of(Enderman.class, NamespacedKey.minecraft("enderman_freeze_when_looked_at"));
  40.     GoalKey<Evoker> EVOKER_ATTACK_SPELL = GoalKey.of(Evoker.class, NamespacedKey.minecraft("evoker_attack_spell"));
  41.     GoalKey<Evoker> EVOKER_CAST_SPELL = GoalKey.of(Evoker.class, NamespacedKey.minecraft("evoker_cast_spell"));
  42.     GoalKey<Evoker> EVOKER_SUMMON_SPELL = GoalKey.of(Evoker.class, NamespacedKey.minecraft("evoker_summon_spell"));
  43.     GoalKey<Evoker> EVOKER_WOLOLO_SPELL = GoalKey.of(Evoker.class, NamespacedKey.minecraft("evoker_wololo_spell"));
  44.     GoalKey<Fish> FISH_SWIM = GoalKey.of(Fish.class, NamespacedKey.minecraft("fish_swim"));
  45.     GoalKey<Fox> FOX_DEFEND_TRUSTED = GoalKey.of(Fox.class, NamespacedKey.minecraft("fox_defend_trusted"));
  46.     GoalKey<Fox> FOX_FACEPLANT = GoalKey.of(Fox.class, NamespacedKey.minecraft("fox_faceplant"));
  47.     GoalKey<Fox> FOX_BREED = GoalKey.of(Fox.class, NamespacedKey.minecraft("fox_breed"));
  48.     GoalKey<Fox> FOX_EAT_BERRIES = GoalKey.of(Fox.class, NamespacedKey.minecraft("fox_eat_berries"));
  49.     GoalKey<Fox> FOX_FLOAT = GoalKey.of(Fox.class, NamespacedKey.minecraft("fox_float"));
  50.     GoalKey<Fox> FOX_FOLLOW_PARENT = GoalKey.of(Fox.class, NamespacedKey.minecraft("fox_follow_parent"));
  51.     GoalKey<Fox> FOX_LOOK_AT_PLAYER = GoalKey.of(Fox.class, NamespacedKey.minecraft("fox_look_at_player"));
  52.     GoalKey<Fox> FOX_MELEE_ATTACK = GoalKey.of(Fox.class, NamespacedKey.minecraft("fox_melee_attack"));
  53.     GoalKey<Fox> FOX_PANIC = GoalKey.of(Fox.class, NamespacedKey.minecraft("fox_panic"));
  54.     GoalKey<Fox> FOX_PERCH_AND_SEARCH = GoalKey.of(Fox.class, NamespacedKey.minecraft("fox_perch_and_search"));
  55.     GoalKey<Fox> FOX_POUNCE = GoalKey.of(Fox.class, NamespacedKey.minecraft("fox_pounce"));
  56.     GoalKey<Fox> FOX_SEARCH_FOR_ITEMS = GoalKey.of(Fox.class, NamespacedKey.minecraft("fox_search_for_items"));
  57.     GoalKey<Fox> FOX_SLEEP = GoalKey.of(Fox.class, NamespacedKey.minecraft("fox_sleep"));
  58.     GoalKey<Fox> FOX_STROLL_THROUGH_VILLAGE = GoalKey.of(Fox.class, NamespacedKey.minecraft("fox_stroll_through_village"));
  59.     GoalKey<Fox> FOX_SEEK_SHELTER = GoalKey.of(Fox.class, NamespacedKey.minecraft("fox_seek_shelter"));
  60.     GoalKey<Fox> FOX_STALK_PREY = GoalKey.of(Fox.class, NamespacedKey.minecraft("fox_stalk_prey"));
  61.     GoalKey<Ghast> GHAST_ATTACK_TARGET = GoalKey.of(Ghast.class, NamespacedKey.minecraft("ghast_attack_target"));
  62.     GoalKey<Ghast> GHAST_IDLE_MOVE = GoalKey.of(Ghast.class, NamespacedKey.minecraft("ghast_idle_move"));
  63.     GoalKey<Ghast> GHAST_MOVE_TOWARDS_TARGET = GoalKey.of(Ghast.class, NamespacedKey.minecraft("ghast_move_towards_target"));
  64.     GoalKey<Guardian> GUARDIAN_ATTACK = GoalKey.of(Guardian.class, NamespacedKey.minecraft("guardian_attack"));
  65.     GoalKey<Illager> RAIDER_OPEN_DOOR = GoalKey.of(Illager.class, NamespacedKey.minecraft("raider_open_door"));
  66.     GoalKey<Illusioner> ILLUSIONER_BLINDNESS_SPELL = GoalKey.of(Illusioner.class, NamespacedKey.minecraft("illusioner_blindness_spell"));
  67.     GoalKey<Illusioner> ILLUSIONER_MIRROR_SPELL = GoalKey.of(Illusioner.class, NamespacedKey.minecraft("illusioner_mirror_spell"));
  68.     GoalKey<Spellcaster> SPELLCASTER_CAST_SPELL = GoalKey.of(Spellcaster.class, NamespacedKey.minecraft("spellcaster_cast_spell"));
  69.     // ......
复制代码

在这里，我们可以很容易的获得到所有 Minecraft 原版 Goal 对应的 GoalKey，然后通过 MobGoals来方便的从一个生物中删除其中一个 Goal，亦或者从一个生物身上获取一个通用的 Goal，再添加到另一个生物身上。

对于 VanillaGoal 的具体实现，不幸的是，因为各种各样的原因，PaperAPI 本身不对外开放 VanillaGoal 的实现，但是通过导入 Paper 服务端，我们可以窥见 VanillaGoal 的真面目：

  1. //
  2. // Source code recreated from a .class file by IntelliJ IDEA
  3. // (powered by FernFlower decompiler)
  4. //

  6. package com.destroystokyo.paper.entity.ai;

  8. import java.util.EnumSet;
  9. import net.minecraft.server.v1_16_R3.PathfinderGoal;
  10. import org.bukkit.entity.Mob;

  12. public class PaperVanillaGoal<T extends Mob> implements VanillaGoal<T> {
  13.     private final PathfinderGoal handle;
  14.     private final GoalKey<T> key;
  15.     private final EnumSet<GoalType> types;

  17.     public PaperVanillaGoal(PathfinderGoal handle) {
  18.         this.handle = handle;
  19.         this.key = MobGoalHelper.getKey(handle.getClass());
  20.         this.types = MobGoalHelper.vanillaToPaper(handle.getGoalTypes());
  21.     }

  23.     public PathfinderGoal getHandle() {
  24.         return this.handle;
  25.     }

  27.     public boolean shouldActivate() {
  28.         return this.handle.shouldActivate2();
  29.     }

  31.     public boolean shouldStayActive() {
  32.         return this.handle.shouldStayActive2();
  33.     }

  35.     public void start() {
  36.         this.handle.start();
  37.     }

  39.     public void stop() {
  40.         this.handle.onTaskReset();
  41.     }

  43.     public void tick() {
  44.         this.handle.tick();
  45.     }

  47.     public GoalKey<T> getKey() {
  48.         return this.key;
  49.     }

  51.     public EnumSet<GoalType> getTypes() {
  52.         return this.types;
  53.     }
  54. }
复制代码

所以实际上，这个所谓的 VanillaGoal 就是一个 Wrapper，用来封装 NMS 的 PathfinderGoal。在使用了 NMS 的环境时，我们也可以直接通过构造一个 PathfinderGoal，然后使用 PaperVanillaGoal 封装，再使用 MobGoal 添加行为到生物身上，以此省去复杂的反射流程。

（正文完）

最后

很多人因为兼容，或者各种原因，不愿意接触 PaperAPI，但是不可否认的是，PaperAPI 确实基于 SpigotAPI 做了太多的拓展和优化，对于一些不那么在意兼容性（比如自用）的情况下，使用 PaperAPI 进行开发，的确可以有效增加开发效率。

（全文完）

来自群组: Complex Studio
w44225769
这个API就有些尴尬。。。想要理解AI运行逻辑，搞这方面开发，基本都要把MC源代码的AI实现了解个七七八八。

ZX夏夜之风
好。
看得我都想学Paper了(过几天就学。。。(
神明点灯y
emmmm羡慕我也想学
GuaGua1020
每日回复帮您顶贴呱呱呱呱呱呱呱呱
gyjsky
众所周知，与 Forge 不同，Bukkit API 总是希望包揽一切，提供一套稳定的，高度封装的 API 给服务端插件开发者，而不希望开发者基于内部代码进行开发。但因为各种原因，原生 Bukkit API（甚至 Spigot API）提供的封装总是有限，对于一些进阶的操作，我们总是需要访问和调用内部代码来实现我们所需要的操作。自定义生物 AI 就是其中的一个：以往，开发者们往往需要自行继承原来的生物实体类，然后重载 Goal 初始化方法，甚至利用反射来添加，或是擦除生物 AI——但有了 Paper API 后，这一切都会变得简单，且可控。
第一页 上一页 下一页 最后一页