@occultus/condition-api 0.22.0-alpha.1

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,30 @@
+# Star Tenon Skill API
+
+本包提供了方便的技能 API。
+
+## 支持版本
+
+本 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,41 @@
+{
+  "name": "@occultus/condition-api",
+  "version": "0.22.0-alpha.1",
+  "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 condition api",
+  "main": "src/index.ts",
+  "keywords": [
+    "Minecraft",
+    "Occultus SDK",
+    "Script API"
+  ],
+  "contributors": [
+    "FangLimao <FangLiulii@outlook.com>"
+  ],
+  "license": "MIT",
+  "author": "CTN Studios",
+  "peerDependencies": {
+    "@minecraft/server": ">=2.0.0",
+    "@occultus/core": ">=0.18.4 || <0.19.0"
+  },
+  "dependencies": {
+    "@occultus/format-api": "0.21.0",
+    "@occultus/item-api": "0.22.0-alpha",
+    "@occultus/entity-api": "0.21.1",
+    "@occultus/text-api": "0.20.0"
+  },
+  "devDependencies": {
+    "typedoc": "^0.28.9"
+  },
+  "scripts": {
+    "test": "tsc"
+  }
+}

package/src/api/Conditions.ts

@@ -0,0 +1,34 @@
+import { Player } from "@minecraft/server";
+import { TextProvider } from "@occultus/text-api";
+
+/**
+ * 条件的抽象类
+ *
+ * 定义了条件的基本结构和必须实现的方法，所有具体的条件类都应该继承此抽象类并实现其抽象方法
+ */
+export abstract class Conditions {
+  /**
+   * @param data 条件所需的数据
+   */
+  constructor(protected data: unknown) {}
+  /**
+   * 检查玩家是否满足条件
+   *
+   * @param player 要检查的玩家对象
+   * @return 如果玩家满足条件返回`true`，否则返回`false`
+   */
+  abstract check(player: Player): boolean;
+  /**
+   * 获取条件的文本，该文本将会在任务面板中显示
+   *
+   * @return 用于显示条件描述的文本
+   */
+  abstract getTextProvider(): TextProvider;
+  /**
+   * 获取条件检查失败时的原因说明文本
+   *
+   * @return 用于显示失败原因的文本
+   */
+  abstract getFailedReason(): TextProvider;
+  
+}

package/src/api/ExpCondition.ts

@@ -0,0 +1,49 @@
+import { Player, RawMessage } from "@minecraft/server";
+import { Conditions } from "./Conditions";
+import { getAllExp } from "@occultus/entity-api";
+
+/**
+ * 等级条件
+ */
+export class ExpConditions extends Conditions {
+  /**
+   * @param experience 满足条件所需的最低等级
+   * @param consumeAmount 倘若为`true`，则条件检查通过后会自动消耗对应等级
+   */
+  constructor(
+    protected experience: number,
+    protected consumeAmount = false
+  ) {
+    super(experience);
+  }
+  check(player: Player) {
+    if (getAllExp(player) >= this.experience) {
+      if (!this.consumeAmount) return true;
+      player.addExperience(-this.experience);
+      return true;
+    }
+    return false;
+  }
+  getTextProvider(): RawMessage {
+    return {
+      rawtext: [
+        // 达到 %s 级
+        {
+          translate: "task.condition.level",
+          with: { text: this.experience.toString() },
+        },
+      ],
+    };
+  }
+  getFailedReason(): RawMessage {
+    return {
+      rawtext: [
+        // 你需要达到 %s 级
+        {
+          translate: "task.condition.level.failed",
+          with: { text: this.experience.toString() },
+        },
+      ],
+    };
+  }
+}

package/src/api/ItemConditions.ts

@@ -0,0 +1,79 @@
+import { ItemStack, Player, RawMessage } from "@minecraft/server";
+import { Conditions } from "./Conditions";
+import {
+  getItemAmountInContainer,
+  removeItemInContainer,
+} from "@occultus/item-api";
+import { TextProvider } from "@occultus/text-api";
+
+/**
+ * 物品条件
+ */
+export class ItemConditions extends Conditions {
+  /**
+   * @param itemType 满足条件所需要的物品类型
+   * @param amount 满足条件所需要的物品数量，默认为 1
+   * @param consumeAmount 倘若为`true`，则条件检查通过后会自动消耗对应物品
+   */
+  constructor(
+    protected itemType: string,
+    protected amount: number = 1,
+    protected consumeAmount = false
+  ) {
+    super(itemType);
+  }
+  /**
+   * 获取条件对应的 ItemStack
+   * @returns 
+   */
+  getItem() {
+    return new ItemStack(this.itemType, this.amount);
+  }
+  /**
+   * 检查玩家是否符合该条件的要求
+   * 
+   * **IMPORTANT: 若`consumeAmount`属性被设置为`true`，则当检查通过时将对玩家的背包进行修改**
+   * @param player 
+   * @return 
+   */
+  check(player: Player) {
+    const container = player.getComponent("minecraft:inventory")?.container;
+    if (!container) return false;
+    const amount = getItemAmountInContainer(container, this.getItem().typeId);
+    if (amount >= this.getItem().amount) {
+      if (!this.consumeAmount) return true;
+      removeItemInContainer(container, this.itemType, this.amount);
+      return true;
+    }
+    return false;
+  }
+  /**
+   * 获得条件对应的 {@link TextProvider}
+   * @returns 
+   */
+  getTextProvider(): RawMessage {
+    return {
+      rawtext: [
+        { translate: this.getItem().localizationKey },
+        { text: " × " },
+        { text: this.getItem().amount.toString() },
+      ],
+    };
+  }
+  /**
+   * 获得条件对应的失败原因
+   * @returns 
+   */
+  getFailedReason(): RawMessage {
+    return {
+      rawtext: [
+        // 你缺少这些物品：
+        { translate: "task.condition.item.failed" },
+        { text: " " },
+        { translate: this.getItem().localizationKey },
+        { text: " × " },
+        { text: this.getItem().amount.toString() },
+      ],
+    };
+  }
+}

package/src/api/KillEntityCondition.ts

@@ -0,0 +1,41 @@
+import { Player, RawMessage } from "@minecraft/server";
+import { Conditions } from "./Conditions";
+import { Localization } from "@occultus/format-api";
+
+/**
+ * 击杀实体条件
+ * 
+ * **IMPORTANT: 此条件必须调用 {@link Task.pushToServer()} 方法才能生效**
+ */
+export class KillEntityConditions extends Conditions {
+  /**
+   * @param entityType 满足条件所需要的实体类型
+   */
+  constructor(
+    public entityType: string
+  ) {
+    super(entityType);
+  }
+  check(player: Player) {
+    return false;
+  }
+  getTextProvider(): RawMessage {
+    return {
+      rawtext: [
+        // 击杀实体：
+        { translate: "task.condition.killentity" },
+        { translate: Localization.getEntityKey(this.entityType) },
+      ],
+    };
+  }
+  getFailedReason(): RawMessage {
+    return {
+      rawtext: [
+        // 你需要击杀实体：
+        { translate: "task.condition.killentity.failed" },
+        { text: " " },
+        { translate: Localization.getEntityKey(this.entityType) },
+      ],
+    };
+  }
+}

package/src/api/KillEntityFamilyCondition.ts

@@ -0,0 +1,41 @@
+import { Player, RawMessage } from "@minecraft/server";
+import { Conditions } from "./Conditions";
+
+/**
+ * 击杀实体条件
+ * 
+ * **IMPORTANT: 此条件必须调用 {@link Task.pushToServer()} 方法才能生效**
+ */
+export class KillEntityFamilyConditions extends Conditions {
+  /**
+   * @param family 满足条件所需要的实体类型
+   */
+  constructor(
+    public family: string,
+    public localizationKey: string
+  ) {
+    super(family);
+  }
+  check(player: Player) {
+    return false;
+  }
+  getTextProvider(): RawMessage {
+    return {
+      rawtext: [
+        // 击杀此类实体：
+        { translate: "task.condition.killEntityFamily" },
+        { translate: this.localizationKey },
+      ],
+    };
+  }
+  getFailedReason(): RawMessage {
+    return {
+      rawtext: [
+        // 你需要击杀此类实体：
+        { translate: "task.condition.killEntityFamily.failed" },
+        { text: " " },
+        { translate: this.localizationKey },
+      ],
+    };
+  }
+}

package/src/api/LevelCondition.ts

@@ -0,0 +1,48 @@
+import { Player, RawMessage } from "@minecraft/server";
+import { Conditions } from "./Conditions";
+
+/**
+ * 等级条件
+ */
+export class LevelConditions extends Conditions {
+  /**
+   * @param level 满足条件所需的最低等级
+   * @param consumeAmount 倘若为`true`，则条件检查通过后会自动消耗对应等级
+   */
+  constructor(
+    protected level: number,
+    protected consumeAmount = false
+  ) {
+    super(level);
+  }
+  check(player: Player) {
+    if (player.level >= this.level) {
+      if (!this.consumeAmount) return true;
+      player.addLevels(-this.level);
+      return true;
+    }
+    return false;
+  }
+  getTextProvider(): RawMessage {
+    return {
+      rawtext: [
+        // 达到 %s 级
+        {
+          translate: "task.condition.level",
+          with: { text: this.level.toString() },
+        },
+      ],
+    };
+  }
+  getFailedReason(): RawMessage {
+    return {
+      rawtext: [
+        // 你需要达到 %s 级
+        {
+          translate: "task.condition.level.failed",
+          with: { text: this.level.toString() },
+        },
+      ],
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @module @occultus/condition-api
+ */
+export * from "./api/ItemConditions";
+export * from "./api/KillEntityCondition";
+export * from "./api/KillEntityFamilyCondition";
+export * from "./api/LevelCondition";
+export * from "./api/ExpCondition";
+export * from "./api/Conditions";

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
+  }
+}