实体 (Entities)

实体是可以以多种方式与世界交互的世界内对象。常见的例子包括生物(mobs)、弹射物(projectiles)、可骑乘对象和玩家。每个实体由多个系统组成，这些系统乍一看可能不易理解。本节将分解与构建实体并使其按照模组开发者意图行为相关的一些关键组件。

术语 (Terminology)

一个简单的实体由三部分组成：

• Entity 子类，它包含我们实体的大部分逻辑
• EntityType，它是已注册的并保存一些通用属性，以及
• EntityRenderer，它负责在游戏中显示实体

更复杂的实体可能需要更多部分。例如，许多更复杂的 EntityRenderer 使用底层的 EntityModel 实例。或者，自然生成的实体将需要某种生成机制(spawn mechanism)。

EntityType

EntityType 和 Entity 之间的关系类似于Items和ItemStacks之间的关系。与 Item 类似，EntityType 是注册到相应注册表（实体类型注册表）的单例，并保存该类型所有实体共有的值，而 Entity，类似于 ItemStack，是该单例类型的“实例”，保存特定于该实体实例的数据。然而，关键区别在于，大部分行为不是在单例 EntityType 中定义的，而是在实例化的 Entity 类本身中定义的。

让我们创建我们的 EntityType 注册表并为其注册一个 EntityType，假设我们有一个扩展 Entity 的类 MyEntity（更多信息见下文）。EntityType.Builder 上的所有方法都是可选的，除了最后的 #build 调用。

public static final DeferredRegister.Entities ENTITY_TYPES =
    DeferredRegister.createEntities(ExampleMod.MOD_ID);

public static final Supplier<EntityType<MyEntity>> MY_ENTITY = ENTITY_TYPES.register(
    "my_entity",
    // 使用构建器创建的实体类型。
    () -> EntityType.Builder.of(
        // EntityType.EntityFactory<T>，其中T是使用的实体类——本例中为 MyEntity。
        // 你可以将其视为 BiFunction<EntityType<T>, Level, T>。
        // 这通常是对实体构造函数的引用。
        MyEntity::new,
        // 我们的实体使用的生物分类(MobCategory)。这主要与生成相关。
        // 更多信息见下文。
        MobCategory.MISC
    )
    // 宽度和高度，以方块为单位。宽度在两个水平方向上都使用。
    // 这也意味着不支持非正方形的足迹。默认值为0.6f和1.8f。
    .sized(1.0f, 1.0f)
    // 由以不同大小生成的生物使用的乘法因子（标量）。
    // 在原版中，这些只有史莱姆和岩浆怪，两者都使用4.0f。
    .spawnDimensionsScale(4.0f)
    // 眼睛高度，从尺寸底部开始计算的方块数。默认为高度 * 0.85。
    // 必须在 #sized 之后调用才能生效。
    .eyeHeight(0.5f)
    // 禁用通过 /summon 召唤实体。
    .noSummon()
    // 防止实体保存到磁盘。
    .noSave()
    // 使实体防火。
    .fireImmune()
    // 使实体对特定方块的伤害免疫。原版使用此功能使
    // 狐狸对甜浆果丛免疫，凋灵和凋灵骷髅对凋零玫瑰免疫，
    // 以及北极熊、雪傀儡和流浪者对细雪免疫。
    .immuneTo(Blocks.POWDER_SNOW)
    // 禁用生成处理程序中的一条规则，该规则限制了实体可以生成的距离。
    // 这意味着无论与玩家的距离如何，此实体都可以生成。
    // 原版为掠夺者和潜影贝启用此功能。
    .canSpawnFarFromPlayer()
    // 客户端保持实体加载的范围，以区块为单位。
    // 此值的原版值各不相同，但通常在8或10左右。默认为5。
    // 请注意，如果此值大于客户端的区块视距，
    // 则实际上会使用该区块视距。
    .clientTrackingRange(8)
    // 此实体的更新数据包发送频率，每x刻一次。对于具有可预测移动模式的实体，
    // 例如弹射物，此值设置得更高。默认为3。
    .updateInterval(10)
    // 使用资源键(resource key)构建实体类型。第二个参数应与实体id相同。
    .build(ResourceKey.create(
        Registries.ENTITY_TYPE,
        ResourceLocation.fromNamespaceAndPath("examplemod", "my_entity")
    ))
);

// 避免样板代码的简写版本。以下调用与
// ENTITY_TYPES.register("my_entity", () -> EntityType.Builder.of(MyEntity::new, MobCategory.MISC).build(
//     ResourceKey.create(Registries.ENTITY_TYPE, ResourceLocation.fromNamespaceAndPath("examplemod", "my_entity"))
// ); 相同
public static final Supplier<EntityType<MyEntity>> MY_ENTITY =
    ENTITY_TYPES.registerEntityType("my_entity", MyEntity::new, MobCategory.MISC);

// 仍然允许通过提供 UnaryOperator<EntityType.Builder> 参数调用其他构建器方法的简写版本。
public static final Supplier<EntityType<MyEntity>> MY_ENTITY = ENTITY_TYPES.registerEntityType(
    "my_entity", MyEntity::new, MobCategory.MISC,
    builder -> builder.sized(2.0f, 2.0f).eyeHeight(1.5f).updateInterval(5));

MobCategory

另请参见自然生成(Natural Spawning)。

实体的 MobCategory 决定了实体的一些属性，这些属性与生成和消失(spawning and despawning)相关。原版默认添加了总共八个 MobCategory：

名称	生成上限	示例
MONSTER	70	各种怪物
CREATURE	10	各种动物
AMBIENT	15	蝙蝠
AXOLOTS	5	美西螈
UNDERGROUND_WATER_CREATURE	5	发光鱿鱼
WATER_CREATURE	5	鱿鱼、海豚
WATER_AMBIENT	20	鱼
MISC	无	所有非生物实体，例如弹射物；使用此 MobCategory 将使实体完全无法自然生成

还有一些其他属性仅在一个或两个 MobCategory 上设置：

• isFriendly：对于 MONSTER 设置为 false，对于所有其他设置为 true。
• isPersistent：对于 CREATURE 和 MISC 设置为 true，对于所有其他设置为 false。
• despawnDistance：对于 WATER_AMBIENT 设置为 64，对于所有其他设置为 128。

信息

MobCategory 是一个可扩展枚举(extensible enum)，意味着你可以向其添加自定义条目。如果这样做，你还需要为此自定义 MobCategory 的实体添加一些生成机制。

实体类 (The Entity Class)

首先，我们创建一个 Entity 子类。除了构造函数，Entity（一个抽象类）定义了四个我们需要实现的必需方法。前三个方法将在数据与网络(Data and Networking)文章中解释，以免进一步臃肿本文，而 #hurtServer 在伤害实体(Damaging Entities)部分中解释。

public class MyEntity extends Entity {
    // 我们继承此构造函数，但没有对泛型通配符的边界。
    // 下面的注册需要边界，因此我们在这里添加它。
    public MyEntity(EntityType<? extends MyEntity> type, Level level) {
        super(type, level);
    }

    // 有关这些方法的信息，请参阅数据与网络文章。
    @Override
    protected void readAdditionalSaveData(ValueInput input) {}

    @Override
    protected void addAdditionalSaveData(ValueOutput output) {}

    @Override
    protected void defineSynchedData(SynchedEntityData.Builder builder) {}

    @Override
    public boolean hurtServer(ServerLevel level, DamageSource damageSource, float amount) {
        return true;
    }
}

信息

虽然可以直接扩展 Entity，但通常更有意义的是使用其众多子类之一作为基础。更多信息请参见实体类层次结构(entity class hierarchy)。

如果需要（例如，因为从代码生成实体），你也可以添加自定义构造函数。这些通常将实体类型硬编码为对已注册对象的引用，如下所示：

public MyEntity(EntityType<? extends MyEntity> type, Level level, double x, double y, double z) {
    // 委托给工厂构造函数，使用我们之前注册的 EntityType。
    this(type, level);
    this.setPos(x, y, z);
}

注意

自定义构造函数永远不应恰好有两个参数，因为这会导致与上面的 (EntityType, Level) 构造函数混淆。

现在，我们可以自由地对我们的实体做任何我们想做的事情。以下小节将展示各种常见的实体用例。

在实体上存储数据 (Data Storage on Entities)

参见实体/数据与网络(Entities/Data and Networking)。

渲染实体 (Rendering Entities)

参见实体/实体渲染器(Entities/Entity Renderers)。

生成实体 (Spawning Entities)

如果我们现在启动游戏并进入世界，我们只有一种生成方式：通过/summon命令（假设没有调用 EntityType.Builder#noSummon）。

显然，我们希望以其他方式添加我们的实体。最简单的方法是通过 LevelWriter#addFreshEntity 方法。该方法简单地接受一个 Entity 实例并将其添加到世界中，如下所示：

// 在某个有 Level 可用的方法中，仅在服务器上
if (!level.isClientSide()) {
    MyEntity entity = new MyEntity(level, 100.0, 200.0, 300.0);
    level.addFreshEntity(entity);
}

或者，你也可以调用 EntityType#spawn，这尤其推荐在生成生物实体(living entities)时使用，因为它会执行一些额外的设置，例如触发生成事件(event)。

这将用于几乎所有的非生物实体。玩家显然不应该自己生成，Mobs有它们自己的生成方式（尽管它们也可以通过 #addFreshEntity 添加），而原版弹射物(projectiles)在 Projectile 类中也有用于生成的静态辅助方法。

伤害实体 (Damaging Entities)

另请参见左键点击物品(Left-Clicking an Item)。

虽然不是所有实体都有生命值的概念，但它们都可以受到伤害。这不仅适用于生物和玩家：如果你想到物品实体（掉落的物品），它们也会受到来自火或仙人掌等来源的伤害，在这种情况下，它们通常会被立即删除。

可以通过调用 Entity#hurt 或 Entity#hurtOrSimulate 来对实体造成伤害，这两个方法之间的区别如下所述。两个方法都接受两个参数：DamageSource和伤害量，以半颗心的浮点数表示。例如，调用 entity.hurt(entity.damageSources().wither(), 4.25) 将造成略多于两颗心的凋零伤害。

反过来，实体也可以修改这种行为。这不是通过重写 #hurt 来完成的，因为它是一个 final 方法。而是有两个方法 #hurtServer 和 #hurtClient，分别处理对应端的伤害逻辑。#hurtClient 通常用于告诉客户端攻击已成功，即使这可能并不总是正确的，主要是为了无论结果如何都播放攻击音效和其他效果。对于更改伤害行为，我们主要关心 #hurtServer，我们可以像这样重写它：

@Override
// 布尔返回值决定实体是否实际受到伤害。
public boolean hurtServer(ServerLevel level, DamageSource damageSource, float amount) {
    if (damageSource.is(DamageTypeTags.IS_FIRE)) {
        // 这假设 super#hurtServer() 已实现。其他常见的方式是
        // 自己设置某个字段。原版实现在不同实体之间差异很大。
        // 值得注意的是，生物实体通常调用 #actuallyHurt，后者又调用 #setHealth。
        return super.hurtServer(level, damageSource, amount * 2);
    } else {
        return false;
    }
}

这种服务器/客户端的分离也是 Entity#hurt 和 Entity#hurtOrSimulate 之间的区别：Entity#hurt 仅在服务器上运行（并调用 Entity#hurtServer），而 Entity#hurtOrSimulate 在两端都运行，根据端调用 Entity#hurtServer 或 Entity#hurtClient。

也可以通过事件修改对不属于你的实体（即由Minecraft或其他模组添加的实体）造成的伤害。这些事件包含许多特定于 LivingEntity 的代码；因此，它们的文档位于生物实体(Living Entities)文章内的伤害事件(Damage Events)部分。

实体刻更新 (Ticking Entities)

很多时候，你会希望你的实体每刻都做一些事情（例如移动）。这个逻辑分布在几个方法中：

• #tick：这是核心的刻更新方法，在99%的情况下你会想要重写它。
  • 默认情况下，这转发给 #baseTick，但几乎每个子类都会重写它。
• #baseTick：此方法处理所有实体通用的一些值的更新，包括“着火”状态、细雪冻结、游泳状态以及通过传送门。LivingEntity 额外在此处理溺水、方块内伤害和伤害追踪器的更新。如果你想更改或添加该逻辑，请重写此方法。
  • 默认情况下，Entity#tick 会转发给此方法。
• #rideTick：此方法针对其他实体的乘客调用，例如玩家骑马，或任何由于使用 /ride 命令而骑乘另一个实体的实体。
  • 默认情况下，此方法执行一些检查，然后调用 #tick。骷髅和玩家重写此方法以特殊处理骑乘实体。

此外，实体有一个名为 tickCount 的字段，表示实体在级别中存在的时间（以刻为单位），以及一个布尔字段 firstTick，这应该是不言自明的。例如，如果你想每5刻生成一个粒子(particle)，可以使用以下代码：

@Override
public void tick() {
    // 除非有充分理由，否则始终调用 super。
    super.tick();
    // 每5刻运行一次此代码。
    if (this.tickCount % 5 == 0) {
        this.level().addParticle(...);
    }
}

选取实体 (Picking Entities)

另请参见中键点击(Middle-Clicking)。

选取(picking)是选择玩家当前正在看的东西的过程，以及随后选取关联的物品。中键点击的结果，称为“选取结果(pick result)”，可以由你的实体修改（注意 Mob 类会为你选择正确的刷怪蛋）：

@Override
@Nullable
public ItemStack getPickResult() {
    // 假设 MY_CUSTOM_ITEM 是一个 DeferredItem<?>，更多信息请参见物品文章。
    // 如果实体不应被选取，建议在此返回 null。
    return new ItemStack(MY_CUSTOM_ITEM.get());
}

虽然实体通常应该是可选取的，但也有一些特殊情况不希望这样。原版的一个用例是末影龙，它由多个部分组成。父实体禁用了选取，但部分又重新启用，以便更精细地调整命中箱。

如果你有类似的特殊用例，你的实体也可以像这样完全禁用选取：

@Override
public boolean isPickable() {
    // 如果需要，可以在此执行其他检查。
    return false;
}

如果你想自己进行选取（即光线投射），可以在要开始光线投射的实体上调用 Entity#pick。这将返回一个HitResult，你可以进一步检查光线投射击中了什么。

实体附件 (Entity Attachments)

不要与数据附件(Data Attachments)混淆。

实体附件用于定义实体的视觉附着点。使用这个系统，可以定义诸如乘客或名称标签相对于实体本身显示的位置。实体本身只控制附件的默认位置，然后附件可以定义相对于该默认位置的偏移。

在构建 EntityType 时，可以通过调用 EntityType.Builder#attach 设置任意数量的附着点。此方法接受一个 EntityAttachment，它定义了要考虑的附件，以及三个浮点数来定义位置（x/y/z）。位置应相对于附件的默认值定义。

原版定义了以下四个 EntityAttachment：

名称	默认值	用途
PASSENGER	命中箱的中心X/顶部Y/中心Z	可骑乘实体，例如马，以定义乘客出现的位置
VEHICLE	命中箱的中心X/底部Y/中心Z	所有实体，以定义它们骑乘另一个实体时出现的位置
NAME_TAG	命中箱的中心X/顶部Y/中心Z	定义实体的名称标签出现的位置（如果适用）
WARDEN_CHEST	命中箱的中心X/中心Y/中心Z	由监守者使用，以定义音波攻击的起源位置

信息

PASSENGER 和 VEHICLE 是相关的，因为它们在同一上下文中使用。首先，应用 PASSENGER 来定位骑乘者。然后，在骑乘者上应用 VEHICLE。

每个附件都可以被视为从 EntityAttachment 到 List<Vec3> 的映射。实际使用的点数取决于消费系统。例如，船和骆驼将使用两个 PASSENGER 点，而像马或矿车这样的实体将只使用一个 PASSENGER 点。

EntityType.Builder 还有一些与 EntityAttachment 相关的辅助方法：

• #passengerAttachment()：用于定义 PASSENGER 附件。有两个变体。
  • 一个变体接受一个 Vec3... 的附着点。
  • 另一个接受一个 float...，它通过将每个浮点数转换为使用给定浮点数作为y值，并将x和z设置为0的 Vec3，转发给 Vec3... 变体。
• #vehicleAttachment()：用于定义 VEHICLE 附件。接受一个 Vec3。
• #ridingOffset()：用于定义 VEHICLE 附件。接受一个浮点数，并转发给 #vehicleAttachment()，其中x和z值设置为0，y值设置为传入浮点数的负值。
• #nameTagOffset()：用于定义 NAME_TAG 附件。接受一个浮点数，用于y值，x和z值使用0。

或者，可以通过调用 EntityAttachments#builder() 然后在该构建器上调用 #attach() 来自定义附件，如下所示：

// 在某个 EntityType<?> 创建中
EntityType.Builder.of(...)
    // 此 EntityAttachment 将使名称标签浮在地面上方半个方块处。
    // 如果未设置，将默认为实体的命中箱高度。
    .attach(EntityAttachment.NAME_TAG, 0, 0.5f, 0)
    .build();

实体类层次结构 (Entity Class Hierarchy)

由于实体类型众多，存在一个复杂的 Entity 子类层次结构。在制作自己的实体时选择要扩展的类时，了解这些很重要，因为通过重用它们的代码，你可以节省大量工作。

原版实体层次结构如下所示（红色类是 abstract，蓝色类不是）：

让我们分解一下：

• Projectile：各种弹射物的基类，包括箭、火球、雪球、烟花和类似实体。更多信息见下文。
• LivingEntity：任何“生物”的基类，即具有生命值、装备、状态效果(mob effects)和其他一些属性的实体。包括怪物、动物、村民和玩家等。更多信息见生物实体(Living Entities)文章。
• BlockAttachedEntity：固定并附着在方块上的实体的基类。包括拴绳结、物品展示框和画。子类的主要目的是重用通用代码。
• PartEntity：NeoForge添加的部分实体的基类，即由多个较小实体组成的实体。EnderDragonPart 被修补为扩展 PartEntity 而不是 Entity。
• VehicleEntity：船和矿车的基类。虽然这些实体与 LivingEntity 松散地共享生命值的概念，但它们与 LivingEntity 不共享许多其他属性，因此保持分离。子类的主要目的是重用通用代码。

还有一些实体直接是 Entity 的子类，仅仅是因为没有其他合适的超类。其中大多数应该是不言自明的：

• AreaEffectCloud（滞留药水云）
• EndCrystal
• EvokerFangs
• ExperienceOrb
• EyeOfEnder
• FallingBlockEntity（下落的沙子、沙砾等）
• ItemEntity（掉落的物品）
• LightningBolt
• OminousItemSpawner（用于持续生成试炼刷怪器的战利品）
• PrimedTnt

此图和列表中未包含地图制作者实体（显示实体、交互实体和标记实体）。

弹射物 (Projectiles)

弹射物是实体的一个子组。它们的共同点是沿一个方向飞行直到击中某物，并且它们有一个分配的所有者（例如，玩家或骷髅可以是箭的所有者，恶魂可以是火球的所有者）。

弹射物的类层次结构如下所示（红色类是 abstract，蓝色类不是）：

值得注意的是 Projectile 的三个直接抽象子类：

• AbstractArrow：此类涵盖不同类型的箭，以及三叉戟。一个重要的共同属性是它们不会直线飞行，而是受重力影响。
• AbstractHurtingProjectile：此类涵盖风弹、各种火球和凋灵之首。这些是不受重力影响的伤害性弹射物。
• ThrowableProjectile：此类涵盖诸如鸡蛋、雪球和末影珍珠之类的东西。与箭一样，它们受重力影响，但与箭不同的是，它们击中目标时不会造成伤害。它们也都是通过使用相应的[物品]生成的。

可以通过扩展 Projectile 或合适的子类来创建新的弹射物，然后重写添加功能所需的方法。常见的重写方法包括：

• #shoot：计算并设置弹射物的正确速度。
• #onHit：当击中某物时调用。
  • #onHitEntity：当该物是[实体]时调用。
  • #onHitBlock：当该物是[方块]时调用。
• #getOwner 和 #setOwner，分别获取和设置所有者实体。
• #deflect，根据传递的 ProjectileDeflection 枚举值偏转弹射物。
• #onDeflection，从 #deflect 调用，用于任何偏转后的行为。