@occultus/toolkit 0.23.3 → 0.23.4

package/src/entity/entityUtils.ts

@@ -1,367 +1,327 @@
-import {
-  Container,
-  Effect,
-  EffectType,
-  Entity,
-  EntityComponentTypes,
-  EntityEffectOptions,
-  EquipmentSlot,
-  ItemStack,
-  Player
-} from "@minecraft/server";
-import { EffectData, effectGroupMap, EffectGroups } from "@occultus/common";
-import { OccultusSDKError } from "@occultus/core";
-import { ensureNoNamespace } from "../identifier/namespace";
-
-/**
- * 尝试对实体进行操作
- *
- * @param entity 要操作的实体
- * @param operate 操作函数，接受一个实体作为参数
- * @returns 操作是否成功
- * @since Starock 0.6.0 (0.1.0)
- */
-export function tryOperateEntity(
-  entity: Entity,
-  operate: (entity: Entity) => void
-): boolean {
-  if (entity.isValid) {
-    operate(entity);
-    return true;
-  }
-  return false;
-}
-
-/**
- * 获取给定**玩家**的指定装备槽物品 {@see EquipmentSlot}
- *
- * 注意：该方法仅适用于玩家实体
- *
- * @param entity 要获取槽位的实体
- * @param slot 要获取的槽位，默认为 {@link EquipmentSlot.Mainhand}
- * @return 槽位中的物品
- * @since Starock 0.6.0 (0.1.0)
- */
-export function getEquipmentItem(
-  entity: Entity,
-  slot = EquipmentSlot.Mainhand
-): ItemStack | undefined {
-  return entity
-    ?.getComponent(EntityComponentTypes.Equippable)
-    ?.getEquipment(slot);
-}
-
-/**
- * 设置给定**玩家**的指定装备槽物品 {@see EquipmentSlot}
- *
- * 注意：该方法仅适用于玩家实体
- *
- * @param entity 要设置槽位的实体
- * @param item 要设置的物品，如果为undefined则清空该槽位
- * @param slot 要设置的槽位，默认为 {@link EquipmentSlot.Mainhand}
- * @since Starock 0.6.0 (0.1.0)
- */
-export function setEquipmentItem(
-  entity: Entity,
-  item?: ItemStack,
-  slot: EquipmentSlot = EquipmentSlot.Mainhand
-): boolean {
-  return (
-    entity
-      ?.getComponent(EntityComponentTypes.Equippable)
-      ?.setEquipment(slot, item) ?? false
-  );
-}
-
-/**
- * 获取实体的容器
- *
- * @param entity 要获取容器的实体
- * @return 实体的容器，如果没有则返回`undefined`
- * @since Starock 0.6.0 (0.1.0)
- */
-export function getContainer(entity: Entity): Container | undefined {
-  return entity.getComponent(EntityComponentTypes.Inventory)?.container;
-}
-
-/**
- * 设置实体的槽位物品
- * @param entity 要设置槽位物品的实体
- * @param slot 槽位索引，从0开始依次递增
- * @param item 要设置的物品
- * @since Starock 0.6.0 (0.1.0)
- */
-export function setSlot(entity: Entity, slot: number, item?: ItemStack): void {
-  getContainer(entity)?.setItem(slot, item);
-}
-
-/**
- * 给予实体物品
- * @param entity 要给予物品的实体
- * @param item 要给予的物品
- * @since Starock 0.6.0 (0.1.0)
- */
-export function giveItem(entity: Entity, item: ItemStack | ItemStack[]): void {
-  const container = getContainer(entity);
-  if (Array.isArray(item)) {
-    for (const i of item) {
-      giveItem(entity, i);
-    }
-    return;
-  }
-  if (container && container.emptySlotsCount > 0) {
-    container.addItem(item);
-  } else {
-    entity.dimension.spawnItem(item, entity.location);
-  }
-}
-
-/**
- * 清空实体的容器
- * @param entity 要清空容器的实体
- * @since Starock 0.6.0 (0.1.0)
- */
-export function clearSlot(entity: Entity): void {
-  getContainer(entity)?.clearAll();
-}
-
-/**
- * 将 {@link EffectData} 应用到实体上
- * @param entity 要应用 {@link EffectData} 的实体
- * @param data 要应用的 {@link EffectData}
- * @returns 应用后的状态效果
- * @since Starock 0.6.0 (0.1.0)
- */
-export function applyEffectData(
-  entity: Entity,
-  data: EffectData | EffectData[]
-): (Effect | undefined)[] {
-  if (!Array.isArray(data)) {
-    data = [data];
-  }
-  return data.flatMap((effectData) => {
-    return entity.addEffect(effectData.effectType, effectData.duration, {
-      amplifier: effectData.amplifier,
-      showParticles: effectData.showParticles
-    });
-  });
-}
-
-/**
- * 向实体移除状态效果
- * @param entity 要清除效果的实体.
- * @param effectType 状态效果类型，可以是单个效果类型、效果类型数组、字符串、字符串数组或{@link EffectGroups}枚举值
- * @since Starock 0.6.0 (0.1.0)
- */
-export function clearEffect(
-  entity: Entity,
-  effectType: EffectType | EffectType[] | string | string[] | EffectGroups
-): void {
-  const effects =
-    effectGroupMap[effectType as EffectGroups] ||
-    (Array.isArray(effectType) ? effectType : [effectType]);
-  for (const effect of effects) {
-    entity.removeEffect(effect);
-  }
-}
-
-/**
- * 向实体添加状态效果
- * @param entity 要添加状态效果实体对象
- * @param effectType 状态效果类型，可以是单个效果类型、效果类型数组、字符串、字符串数组或{@link EffectGroups}枚举值
- * @param duration
- * 状态效果持续时间，以刻为单位 *（20刻 = 1秒）*
- *
- * 其值必须在范围`[0, 20000000]`内
- *
- * 如果值为`"infinite"`，则状态效果将无限期持续
- * @param options 状态效果选项
- * @since Starock 0.6.0 (0.1.0)
- */
-export function addEffect(
-  entity: Entity,
-  effectType: EffectType | EffectType[] | string | string[] | EffectGroups,
-  duration: number | "infinite",
-  options?: EntityEffectOptions
-): void {
-  const effects =
-    effectGroupMap[effectType as EffectGroups] ||
-    (Array.isArray(effectType) ? effectType : [effectType]);
-  for (const effect of effects) {
-    if (duration === "infinite") {
-      entity.runCommand(
-        // @ts-ignore
-        `effect @s ${ensureNoNamespace(effect)} infinite ${options?.amplifier ?? 0} ${options?.showParticles ?? false}`
-      );
-      return;
-    }
-    entity.addEffect(effect, duration, options);
-  }
-}
-
-/**
- * 获取实体所有的族
- * @param entity 要获取族的实体
- * @return 实体的族数组，如果没有则返回`undefined`
- * @see https://zh.minecraft.wiki/w/族
- * @see https://minecraft.wiki/w/Family
- */
-export function getFamilies(entity: Entity): string[] | undefined {
-  return entity.getComponent("minecraft:type_family")?.getTypeFamilies();
-}
-
-/**
- * 返回实体是否含有指定族
- * @param entity 要检查族的实体
- * @return 实体是否含有指定族
- * @see https://zh.minecraft.wiki/w/族
- * @see https://minecraft.wiki/w/Family
- */
-export function hasFamily(entity: Entity, family: string): boolean {
-  return (
-    entity.getComponent("minecraft:type_family")?.hasTypeFamily(family) ?? false
-  );
-}
-
-/**
- * 根据玩家等级计算经验消耗
- * @param level 玩家等级
- */
-export function getExpCost(level: number): number {
-  if (level >= 30) {
-    return 62 + (level - 30) * 7;
-  }
-  if (level >= 15) {
-    return 17 + (level - 15) * 3;
-  }
-  return 17;
-}
-
-/**
- * 获取玩家得到的所有经验值
- * @param player
- */
-export function getAllExp(player: Player): number {
-  const level: number = player.level;
-  let exp = 0;
-  for (let i = 1; i <= level; i++) {
-    exp += getExpCost(i);
-  }
-  return exp + player.xpEarnedAtCurrentLevel;
-}
-
-function consumeAmount(item: ItemStack, value: number): ItemStack | undefined {
-  const amount: number = item.amount;
-  if (amount === value) {
-    return undefined;
-  }
-  if (amount - value < 0) {
-    throw new OccultusSDKError(
-      `The number of items is insufficient! Actual amount: ${amount} Consume amount: ${value}`,
-      `${item.typeId}`
-    );
-  }
-  if (amount - value > item.maxAmount) {
-    throw new OccultusSDKError(
-      `The max stack of items is insufficient!`,
-      `${item.typeId}`
-    );
-  }
-  const newItem: ItemStack = item.clone();
-  newItem.amount = amount - value;
-  return newItem;
-}
-
-/**
- * 消耗玩家装备物品的数量
- * @param player 要消耗物品的玩家
- * @param amount 消耗的数量
- * @returns 是否消耗成功
- */
-export function consumeEquipmentAmount(
-  player: Player,
-  amount: number = 1
-): boolean {
-  const item = getEquipmentItem(player);
-  if (!item) return false;
-  return setEquipmentItem(player, consumeAmount(item, amount));
-}
-
-/**
- * 恢复实体的生命值
- * @param entity 将要被治疗的实体
- * @param amount 恢复的生命值，若治愈后生命值超过最大生命值，则重置为最大生命值
- * @return 治愈后的生命值
- * @throws 如果实体没有`minecraft:health`组件，则抛出`OccultusSDKError`
- */
-export function heal(entity: Entity, amount: number): number {
-  const health = entity.getComponent("minecraft:health");
-  if (!health)
-    throw new OccultusSDKError("The entity does not have health component!");
-  const newHealth = health.currentValue + amount;
-  if (newHealth > health.effectiveMax) {
-    health.resetToMaxValue();
-    return health.effectiveMax;
-  } else health.setCurrentValue(newHealth);
-  return newHealth;
-}
-
-/**
- * 获取实体当前生命值
- * @param entity 要获取生命值的实体
- * @returns 
- */
-export function getCurrentHealth(entity: Entity): number {
-  const health = entity.getComponent("minecraft:health");
-  if (!health)
-    throw new OccultusSDKError("The entity does not have health component!");
-  return health.currentValue;
-}
-
-/**
- * 设置实体当前生命值
- * @param entity 要设置生命值的实体
- * @param value 要设置的生命值，若超出实体最大生命值，则重置为最大生命值
- * @returns 
- */
-export function setCurrentHealth(entity: Entity, value: number): number {
-  const health = entity.getComponent("minecraft:health");
-  if (!health)
-    throw new OccultusSDKError("The entity does not have health component!");
-  if(value > health.effectiveMax) {
-    health.resetToMaxValue();
-    return health.effectiveMax;
-  }
-  health.setCurrentValue(value);
-  return value;
-}
-
-/**
- * 消耗实体生命值，这一行为不会被视为攻击
- * @param entity 
- * @param amount 
- * @returns 
- */
-export function consumeHealth(entity: Entity, amount: number): number {
-  const newHealth = getCurrentHealth(entity) - amount;
-  if(newHealth <= 0) {
-    entity.kill();
-    return 0;
-  }
-  return setCurrentHealth(entity, getCurrentHealth(entity) - amount);
-}
-
-/**
- * 以指定倍率消耗实体的生命值，这一行为不会被视为攻击
- * @param entity 
- * @param amplifier 消耗生命的倍率，例如`0.8`将会被视为消耗实体当前 80% 的生命值
- * @returns 
- */
-export function consumeHealthAmplifier(entity: Entity, amplifier: number): number {
-  const newHealth = getCurrentHealth(entity) - (getCurrentHealth(entity) * amplifier);
-  if(newHealth <= 0) {
-    entity.kill();
-    return 0;
-  }
-  return setCurrentHealth(entity, newHealth);
-}
+import {
+  Container,
+  Effect,
+  EffectType,
+  Entity,
+  EntityComponentTypes,
+  EntityEffectOptions,
+  EquipmentSlot,
+  ItemStack,
+  Player
+} from "@minecraft/server";
+import { EffectData, effectGroupMap, EffectGroups } from "@occultus/common";
+import { OccultusSDKError } from "@occultus/core";
+import { ensureNoNamespace } from "../identifier/namespace";
+import { EntityHealthUtils } from "./health";
+
+/**
+ * 尝试对实体进行操作
+ *
+ * @param entity 要操作的实体
+ * @param operate 操作函数，接受一个实体作为参数
+ * @returns 操作是否成功
+ * @since Starock 0.6.0 (0.1.0)
+ */
+export function tryOperateEntity(
+  entity: Entity,
+  operate: (entity: Entity) => void
+): boolean {
+  if (entity.isValid) {
+    operate(entity);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * 获取给定**玩家**的指定装备槽物品 {@see EquipmentSlot}
+ *
+ * 注意：该方法仅适用于玩家实体
+ *
+ * @param entity 要获取槽位的实体
+ * @param slot 要获取的槽位，默认为 {@link EquipmentSlot.Mainhand}
+ * @return 槽位中的物品
+ * @since Starock 0.6.0 (0.1.0)
+ */
+export function getEquipmentItem(
+  entity: Entity,
+  slot = EquipmentSlot.Mainhand
+): ItemStack | undefined {
+  return entity
+    ?.getComponent(EntityComponentTypes.Equippable)
+    ?.getEquipment(slot);
+}
+
+/**
+ * 设置给定**玩家**的指定装备槽物品 {@see EquipmentSlot}
+ *
+ * 注意：该方法仅适用于玩家实体
+ *
+ * @param entity 要设置槽位的实体
+ * @param item 要设置的物品，如果为undefined则清空该槽位
+ * @param slot 要设置的槽位，默认为 {@link EquipmentSlot.Mainhand}
+ * @since Starock 0.6.0 (0.1.0)
+ */
+export function setEquipmentItem(
+  entity: Entity,
+  item?: ItemStack,
+  slot: EquipmentSlot = EquipmentSlot.Mainhand
+): boolean {
+  return (
+    entity
+      ?.getComponent(EntityComponentTypes.Equippable)
+      ?.setEquipment(slot, item) ?? false
+  );
+}
+
+/**
+ * 获取实体的容器
+ *
+ * @param entity 要获取容器的实体
+ * @return 实体的容器，如果没有则返回`undefined`
+ * @since Starock 0.6.0 (0.1.0)
+ */
+export function getContainer(entity: Entity): Container | undefined {
+  return entity.getComponent(EntityComponentTypes.Inventory)?.container;
+}
+
+/**
+ * 设置实体的槽位物品
+ * @param entity 要设置槽位物品的实体
+ * @param slot 槽位索引，从0开始依次递增
+ * @param item 要设置的物品
+ * @since Starock 0.6.0 (0.1.0)
+ */
+export function setSlot(entity: Entity, slot: number, item?: ItemStack): void {
+  getContainer(entity)?.setItem(slot, item);
+}
+
+/**
+ * 给予实体物品
+ * @param entity 要给予物品的实体
+ * @param item 要给予的物品
+ * @since Starock 0.6.0 (0.1.0)
+ */
+export function giveItem(entity: Entity, item: ItemStack | ItemStack[]): void {
+  const container = getContainer(entity);
+  if (Array.isArray(item)) {
+    for (const i of item) {
+      giveItem(entity, i);
+    }
+    return;
+  }
+  if (container && container.emptySlotsCount > 0) {
+    container.addItem(item);
+  } else {
+    entity.dimension.spawnItem(item, entity.location);
+  }
+}
+
+/**
+ * 清空实体的容器
+ * @param entity 要清空容器的实体
+ * @since Starock 0.6.0 (0.1.0)
+ */
+export function clearSlot(entity: Entity): void {
+  getContainer(entity)?.clearAll();
+}
+
+/**
+ * 将 {@link EffectData} 应用到实体上
+ * @param entity 要应用 {@link EffectData} 的实体
+ * @param data 要应用的 {@link EffectData}
+ * @returns 应用后的状态效果
+ * @since Starock 0.6.0 (0.1.0)
+ */
+export function applyEffectData(
+  entity: Entity,
+  data: EffectData | EffectData[]
+): (Effect | undefined)[] {
+  if (!Array.isArray(data)) {
+    data = [data];
+  }
+  return data.flatMap((effectData) => {
+    return entity.addEffect(effectData.effectType, effectData.duration, {
+      amplifier: effectData.amplifier,
+      showParticles: effectData.showParticles
+    });
+  });
+}
+
+/**
+ * 向实体移除状态效果
+ * @param entity 要清除效果的实体.
+ * @param effectType 状态效果类型，可以是单个效果类型、效果类型数组、字符串、字符串数组或{@link EffectGroups}枚举值
+ * @since Starock 0.6.0 (0.1.0)
+ */
+export function clearEffect(
+  entity: Entity,
+  effectType: EffectType | EffectType[] | string | string[] | EffectGroups
+): void {
+  const effects =
+    effectGroupMap[effectType as EffectGroups] ||
+    (Array.isArray(effectType) ? effectType : [effectType]);
+  for (const effect of effects) {
+    entity.removeEffect(effect);
+  }
+}
+
+/**
+ * 向实体添加状态效果
+ * @param entity 要添加状态效果实体对象
+ * @param effectType 状态效果类型，可以是单个效果类型、效果类型数组、字符串、字符串数组或{@link EffectGroups}枚举值
+ * @param duration
+ * 状态效果持续时间，以刻为单位 *（20刻 = 1秒）*
+ *
+ * 其值必须在范围`[0, 20000000]`内
+ *
+ * 如果值为`"infinite"`，则状态效果将无限期持续
+ * @param options 状态效果选项
+ * @since Starock 0.6.0 (0.1.0)
+ */
+export function addEffect(
+  entity: Entity,
+  effectType: EffectType | EffectType[] | string | string[] | EffectGroups,
+  duration: number | "infinite",
+  options?: EntityEffectOptions
+): void {
+  const effects =
+    effectGroupMap[effectType as EffectGroups] ||
+    (Array.isArray(effectType) ? effectType : [effectType]);
+  for (const effect of effects) {
+    if (duration === "infinite") {
+      entity.runCommand(
+        // @ts-ignore
+        `effect @s ${ensureNoNamespace(effect)} infinite ${options?.amplifier ?? 0} ${options?.showParticles ?? false}`
+      );
+      return;
+    }
+    entity.addEffect(effect, duration, options);
+  }
+}
+
+/**
+ * 获取实体所有的族
+ * @param entity 要获取族的实体
+ * @return 实体的族数组，如果没有则返回`undefined`
+ * @see https://zh.minecraft.wiki/w/族
+ * @see https://minecraft.wiki/w/Family
+ */
+export function getFamilies(entity: Entity): string[] | undefined {
+  return entity.getComponent("minecraft:type_family")?.getTypeFamilies();
+}
+
+/**
+ * 返回实体是否含有指定族
+ * @param entity 要检查族的实体
+ * @return 实体是否含有指定族
+ * @see https://zh.minecraft.wiki/w/族
+ * @see https://minecraft.wiki/w/Family
+ */
+export function hasFamily(entity: Entity, family: string): boolean {
+  return (
+    entity.getComponent("minecraft:type_family")?.hasTypeFamily(family) ?? false
+  );
+}
+
+/**
+ * 根据玩家等级计算经验消耗
+ * @param level 玩家等级
+ */
+export function getExpCost(level: number): number {
+  if (level >= 30) {
+    return 62 + (level - 30) * 7;
+  }
+  if (level >= 15) {
+    return 17 + (level - 15) * 3;
+  }
+  return 17;
+}
+
+/**
+ * 获取玩家得到的所有经验值
+ * @param player
+ */
+export function getAllExp(player: Player): number {
+  const level: number = player.level;
+  let exp = 0;
+  for (let i = 1; i <= level; i++) {
+    exp += getExpCost(i);
+  }
+  return exp + player.xpEarnedAtCurrentLevel;
+}
+
+function consumeAmount(item: ItemStack, value: number): ItemStack | undefined {
+  const amount: number = item.amount;
+  if (amount === value) {
+    return undefined;
+  }
+  if (amount - value < 0) {
+    throw new OccultusSDKError(
+      `The number of items is insufficient! Actual amount: ${amount} Consume amount: ${value}`,
+      `${item.typeId}`
+    );
+  }
+  if (amount - value > item.maxAmount) {
+    throw new OccultusSDKError(
+      `The max stack of items is insufficient!`,
+      `${item.typeId}`
+    );
+  }
+  const newItem: ItemStack = item.clone();
+  newItem.amount = amount - value;
+  return newItem;
+}
+
+/**
+ * 消耗玩家装备物品的数量
+ * @param player 要消耗物品的玩家
+ * @param amount 消耗的数量
+ * @returns 是否消耗成功
+ */
+export function consumeEquipmentAmount(
+  player: Player,
+  amount: number = 1
+): boolean {
+  const item = getEquipmentItem(player);
+  if (!item) return false;
+  return setEquipmentItem(player, consumeAmount(item, amount));
+}
+
+/**
+ * @deprecated 请使用 {@link EntityHealthUtils.heal}
+ */
+export function heal(entity: Entity, amount: number): number {
+  return new EntityHealthUtils(entity).heal(amount);
+}
+
+/**
+ * @deprecated 请使用 {@link EntityHealthUtils.current}
+ */
+export function getCurrentHealth(entity: Entity): number {
+  return new EntityHealthUtils(entity).current;
+}
+
+/**
+ * @deprecated 请使用 {@link EntityHealthUtils.current}
+ */
+export function setCurrentHealth(entity: Entity, value: number): number {
+  return (new EntityHealthUtils(entity).current = value);
+}
+
+/**
+ * @deprecated 请使用 {@link EntityHealthUtils.damage}
+ */
+export function consumeHealth(entity: Entity, amount: number): number {
+  return new EntityHealthUtils(entity).damage(amount);
+}
+
+/**
+ * @deprecated 请使用 {@link EntityHealthUtils.damageWithAmplifier}
+ */
+export function consumeHealthAmplifier(
+  entity: Entity,
+  amplifier: number
+): number {
+  return new EntityHealthUtils(entity).damageWithAmplifier(amplifier);
+}