@occultus/entity-api/src/utils/EntitiesUtils.ts

Star Tenon entity api and utils

import {
  Dimension,
  EntityQueryOptions,
  Entity,
  EntityApplyDamageByProjectileOptions,
  EntityApplyDamageOptions,
  EffectType,
  EntityEffectOptions,
  ItemStack,
} from "@minecraft/server";
import { EffectGroups, EffectData } from "@occultus/common";
import { addEffect, applyEffectData, clearSlot, giveItem } from "./entityUtils";

/**
 * 适用于批量实体的相关工具
 * @since Starock 0.6.0 (0.1.0)
 * @example
 * new EntitiesUtils(world.getDimension("overworld"), {
 *   type: "minecraft:player",
 * }).damage(10);
 */

export class EntitiesUtils {
  /**
   * @param dimension 实体所在的维度
   * @param queryOption 查询实体的选项
   */
  constructor(
    public dimension: Dimension,
    public queryOption: EntityQueryOptions
  ) {}
  /**
   * 查询给定条件下的实体
   * @returns
   */
  query(): Entity[] {
    return this.dimension.getEntities(this.queryOption);
  }
  /**
   * 尝试对实体进行操作
   * @param operate 操作函数，接受一个实体作为参数
   */
  tryOperateEntity(operate: (entity: Entity) => void) {
    this.query().forEach((entity) => {
      if (entity.isValid) {
        operate(entity);
      }
    });
  }
  /**
   * 对批量实体进行伤害
   * @param amount 施加的伤害量
   * @param options 关于伤害来源的额外选项，可能会增加额外的效果或造成受伤实体的额外行为
   * @since Starock 0.6.0 (0.1.0)
   */
  applyDamage(
    amount: number,
    options?: EntityApplyDamageByProjectileOptions | EntityApplyDamageOptions
  ) {
    this.query().forEach((entity) => entity.applyDamage(amount, options));
  }
  /**
   * 为批量实体添加效果
   *
   * @param effectType 效果的类型
   * @param duration
   * 效果持续时间，以刻为单位 *（20刻=1秒）*
   *
   * 其值必须在范围`[0, 20000000]`内
   * @param effectOption 可选参数，状态效果的具体配置选项
   * @since Starock 0.6.0 (0.1.0)
   */
  addEffect(
    effectType: EffectType | EffectType[] | string | string[] | EffectGroups,
    duration: number,
    effectOption?: EntityEffectOptions
  ) {
    this.query().forEach((entity) =>
      addEffect(entity, effectType, duration, effectOption)
    );
  }
  /**
   * 批量给予实体物品
   * @param entity 要给予物品的实体
   * @param item 要给予的物品
   * @since Starock 0.6.0 (0.1.0)
   */
  giveItem(item: ItemStack) {
    this.query().forEach((entity) => giveItem(entity, item));
  }
  /**
   * 批量清空实体的容器
   * @since Starock 0.6.0 (0.1.0)
   */
  clearSlot(): void {
    this.query().forEach((entity) => clearSlot(entity));
  }
  /**
   * 批量为实体应用 {@link EffectData }
   * @param data 要应用的 {@link EffectData }
   * @returns
   */
  applyEffectData(data: EffectData | EffectData[]): void {
    return this.query().forEach((entity) =>
      applyEffectData(entity, data)
    );
  }
}