@occultus/toolkit 0.22.0

package/LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright © 2025 CTN Studios
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,31 @@
+# Star Tenon Toolkit
+
+一个轻量的 API 工具包，包括一些常用的工具函数，可用于实体以及 ItemStack。
+
+## 支持版本
+
+本 API 支持任意可以运行 Script API v2.0.0+ 的游戏版本，包括：
+
+- 1.21.90；
+- 1.21.100；
+- 1.21.110；
+- 以及更多……
+
+注意：本包理论上可以在部分更旧的版本上运作，但未经过严格的测试。
+
+## 协议
+
+本项目使用 MIT License 授权：
+
+```text
+The MIT License (MIT)
+
+Copyright © 2025 CTN Studios
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```
+

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@occultus/toolkit",
+  "version": "0.22.0",
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/TeamOccultus/StarTenonAPI"
+  },
+  "homepage": "https://codeberg.org/TeamOccultus/StarTenonAPI",
+  "bugs": {
+    "url": "https://codeberg.org/TeamOccultus/StarTenonAPI/issues",
+    "email": "FangLiulii@outlook.com"
+  },
+  "description": "Star Tenon api toolkit",
+  "main": "src/index.ts",
+  "keywords": [
+    "Minecraft",
+    "Occultus SDK",
+    "Script API"
+  ],
+  "contributors": [
+    "FangLimao <FangLiulii@outlook.com>"
+  ],
+  "license": "MIT",
+  "author": "CTN Studios",
+  "dependencies": {},
+  "peerDependencies": {
+    "@minecraft/server": ">=2.0.0",
+    "@minecraft/server-ui": ">=2.0.0",
+    "@occultus/core": ">=0.18.4 || <0.19.0",
+    "@occultus/common": "0.20.0"
+  },
+  "devDependencies": {
+    "typedoc": "^0.28.9"
+  },
+  "scripts": {
+    "test": "tsc"
+  }
+}

package/src/entity/EntitiesUtils.ts

@@ -0,0 +1,108 @@
+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)
+    );
+  }
+}

package/src/entity/entityUtils.ts

@@ -0,0 +1,277 @@
+import {
+  Container,
+  Effect,
+  EffectType,
+  Entity,
+  EntityEffectOptions,
+  EntityEquippableComponent,
+  EquipmentSlot,
+  ItemStack,
+  Player,
+} from "@minecraft/server";
+import { EffectData, effectGroupMap, EffectGroups } from "@occultus/common";
+import { OccultusSDKError } from "@occultus/core";
+
+/**
+ * 尝试对实体进行操作
+ *
+ * @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;
+}
+
+/**
+ * 获取给定实体的指定槽位物品
+ *
+ * **IMPORTANT: 受原版接口限制， 当前只能获取玩家的装备**
+ * @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 {
+  const equipment = entity?.getComponent(
+    "minecraft:equippable"
+  ) as EntityEquippableComponent;
+  return equipment?.getEquipment(slot);
+}
+
+/**
+ * 设置给定实体的指定槽位物品
+ *
+ * **IMPORTANT: 受原版接口限制， 当前只能获取玩家的装备**
+ * @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 {
+  const equipment = entity?.getComponent(
+    "minecraft:equippable"
+  ) as EntityEquippableComponent;
+  if (!equipment) return false;
+  return equipment?.setEquipment(slot, item);
+}
+
+/**
+ * 获取实体的容器
+ *
+ * @param entity 要获取容器的实体
+ * @return 实体的容器，如果没有则返回`undefined`
+ * @since Starock 0.6.0 (0.1.0)
+ */
+export function getContainer(entity: Entity): Container | undefined {
+  return entity.getComponent("minecraft: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]`内
+ * @param options 状态效果选项
+ * @since Starock 0.6.0 (0.1.0)
+ */
+export function addEffect(
+  entity: Entity,
+  effectType: EffectType | EffectType[] | string | string[] | EffectGroups,
+  duration: number,
+  options?: EntityEffectOptions
+): void {
+  const effects =
+    effectGroupMap[effectType as EffectGroups] ||
+    (Array.isArray(effectType) ? effectType : [effectType]);
+  for (const effect of effects) {
+    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));
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @module toolkit
+ */
+export * from "./entity/EntitiesUtils"
+export * from "./entity/entityUtils"
+export * from "./item/item"
+export * from "./item/container"

package/src/item/container.ts

@@ -0,0 +1,95 @@
+import { Container, ItemStack } from "@minecraft/server";
+
+/**
+ * 获取容器中指定物品的数量
+ * @param container 容器对象
+ * @param typeId 要获取的物品 ID
+ * @returns 容器中指定物品的数量
+ * @author RawDiamondMC
+ */
+
+export function getItemAmountInContainer(
+  container: Container,
+  typeId: string
+): number {
+  let amount = 0;
+  for (let slot = 0; slot < container.size; slot++) {
+    const itemStack: undefined | ItemStack = container.getItem(slot);
+    if (itemStack?.typeId === typeId) {
+      amount += itemStack.amount;
+    }
+  }
+  return amount;
+}
+
+/**
+ * 从容器中移除指定数量的物品
+ * @param container 容器对象
+ * @param typeId 物品 ID
+ * @param amount 要移除物品的数量
+ * @author RawDiamondMC
+ */
+export function removeItemInContainer(
+  container: Container,
+  typeId: string,
+  amount: number
+): void {
+  for (let slot = 0; slot < container.size; slot++) {
+    const itemStack: undefined | ItemStack = container.getItem(slot);
+    if (itemStack?.typeId === typeId) {
+      if (itemStack.amount > amount) {
+        itemStack.amount -= amount;
+        container.setItem(slot, itemStack);
+        return;
+      }
+      container.setItem(slot);
+      amount -= itemStack.amount;
+    }
+  }
+}
+
+/**
+ * 在容器中查找替换物品
+ * @param item 要替换的物品，如果为`undefined`，则替换所有空槽
+ * @param newItem 替换后的物品，如果为`undefined`，则清空所有物品
+ * @param container 要搜索的容器
+ * @author RawDiamondMC
+ */
+export function replaceItemStack(
+  item: ItemStack | undefined,
+  newItem: ItemStack | undefined,
+  container: Container
+): number {
+  let amount = 0;
+  for (let slot = 0; slot < container.size; slot++) {
+    const itemStack: undefined | ItemStack = container.getItem(slot);
+    if (itemStack?.typeId === item?.typeId) {
+      container.setItem(slot, newItem);
+      amount++;
+    }
+  }
+  return amount;
+}
+
+/**
+ * 在容器中根据标签查找替换物品
+ * @param itemTag 要替换的物品标签
+ * @param newItem 替换后的物品，如果为`undefined`，则清空所有物品
+ * @param container 要搜索的容器
+ */
+
+export function replaceItemByTag(
+  itemTag: string,
+  newItem: ItemStack | undefined,
+  container: Container
+): number {
+  let amount = 0;
+  for (let slot = 0; slot < container.size; slot++) {
+    const itemStack: undefined | ItemStack = container.getItem(slot);
+    if (itemStack?.hasTag(itemTag)) {
+      container.setItem(slot, newItem);
+      amount++;
+    }
+  }
+  return amount;
+}

package/src/item/item.ts

@@ -0,0 +1,94 @@
+import {
+  ItemStack,
+  Entity,
+  ItemComponent,
+  ItemComponentTypes,
+  ItemDurabilityComponent,
+  Player,
+  GameMode,
+} from "@minecraft/server";
+import { OccultusSDKError } from "@occultus/core";
+
+/**
+ * 添加物品的损坏值，即消耗其耐久。当`entity`是创造模式或是`undefined`，会直接返回`item`
+ * @param item 要添加损坏值的物品
+ * @param value 要添加的损坏值
+ * @param entity 当物品损坏时，向手持物品的实体播放声音
+ * @returns 添加损坏值的 {@link ItemStack}
+ * @author RawDiamondMC, FangLimao
+ */
+export function consumeDurability(
+  item: ItemStack,
+  value: number,
+  entity?: Entity
+): ItemStack | undefined {
+  const isPlayer = entity instanceof Player;
+  if (isPlayer && entity.getGameMode() === GameMode.Creative) {
+    // 创造模式下不消耗物品耐久
+    return item;
+  }
+  const durability: undefined | ItemComponent = item.getComponent(
+    ItemComponentTypes.Durability
+  );
+  if (
+    durability === undefined ||
+    !(durability instanceof ItemDurabilityComponent)
+  ) {
+    return item;
+  }
+  if (durability.damage + value >= durability.maxDurability) {
+    if (isPlayer) {
+      entity.playSound("random.break");
+    }
+    return undefined;
+  }
+  durability.damage += value;
+  return item;
+}
+
+/**
+ * 消耗物品的数量
+ * @param item 要消耗物品的数量
+ * @param value 要消耗的数量
+ * @returns 消耗后的物品堆
+ * @throws 如果物品数量不足，则抛出错误
+ * @author RawDiamondMC
+ */
+export 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;
+}
+
+/**
+ * 向物品添加新的 Lore
+ * @param loreText 要添加的 Lore文本
+ * @param item 要添加 Lore 文本的物品
+ * @returns 更新 Lore 后的物品
+ * @author FangLimao
+ */
+export function pushLore(loreText: string, item: ItemStack): ItemStack {
+  const lore = item.getLore();
+  lore.push(loreText);
+  item.setLore(lore);
+  return item;
+}

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "include": ["src/**/*"],
+  "exclude": ["./out"],
+  "Modules": {
+    "resolvePackageJsonExports": true
+  },
+  "compilerOptions": {
+    "noEmit": true,
+    "noEmitOnError": true,
+    "target": "es2022",
+    "lib": ["es2020", "dom"],
+    "strict": true,
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "module": "es2022",
+    "outDir": ".",
+    "removeComments": true,
+    "newLine": "lf",
+    "resolveJsonModule": true
+  }
+}