@occultus/random-api 0.18.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 @@
+# Starock Random

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@occultus/random-api",
+  "version": "0.18.1",
+  "description": "Star Tenon random api",
+  "main": "src/index.ts",
+  "keywords": [
+    "Minecraft",
+    "Occultus SDK",
+    "Script API"
+  ],
+  "contributors": [
+    "FangLimao <mucigames@outlook.com>",
+    "RawDiamondMC <RawDiamondMC@outlook.com>"
+  ],
+  "license": "MIT",
+  "author": "CTN Studios",
+  "dependencies": {
+    "@occultus/math-api": "0.18.1"
+  },
+  "peerDependencies": {
+    "@minecraft/server": "2.3.0-beta.1.21.110-preview.20",
+    "@occultus/core": ">=0.18.2 || <0.19.0"
+  },
+  "devDependencies": {
+    "typedoc": "^0.28.9"
+  }
+}

package/src/api/Random.ts

@@ -0,0 +1,73 @@
+import { system } from "@minecraft/server";
+
+export class Random {
+  /**
+   * 生成随机整数
+   * @param max 最大值，小数部分将被解析为整数
+   * @param min 最小值，小数部分将被解析为整数，默认为0
+   * @param inclusive 生成的随机数是否包含最小值和最大值，默认为true
+   * @return 在最小值和最大值之间的一个随机整数
+   * @throws 如果 max < min，则抛出 RangeError
+   */
+  static integer(max: number, min = 0, inclusive = true): number {
+    max = Math.ceil(max);
+    min = Math.ceil(min);
+    if (max < min) {
+      throw new RangeError(
+        `randomInteger() is used incorrectly! Expect: any number higher than ${min}. Current: ${max}`
+      );
+    }
+    if (inclusive) {
+      return Math.floor(Math.random() * (max - min + 1)) + min;
+    }
+    return Math.floor(Math.random() * (max - min)) + min;
+  }
+
+  /**
+   * 生成随机小数
+   * @param max 最大值，小数部分将被解析为整数
+   * @param min 最小值，小数部分将被解析为整数，默认为0
+   * @param fixed 保留的小数位数。默认为2
+   * @param inclusive 生成的随机数是否包含最小值和最大值，默认为true
+   * @return 在最小值和最大值之间的一个随机小数
+   * @throws 如果 max < min，则抛出 RangeError
+   */
+  static decimal(max: number, min = 0, fixed = 2, inclusive = true): number {
+    max = Math.ceil(max);
+    min = Math.ceil(min);
+    if (max < min) {
+      throw new RangeError(
+        `randomDecimal() is used incorrectly! Expect: any number higher than ${min}. Current: ${max}`
+      );
+    }
+    let random: number;
+    if (inclusive) {
+      random = Math.random() * (max - min + 1) + min;
+    } else {
+      random = Math.random() * (max - min) + min;
+    }
+    if (fixed) {
+      return Number(random.toFixed(fixed));
+    }
+    return random;
+  }
+
+  /**
+   * 生成一个 UUID
+   * @return 一个字符串形式的 UUID
+   */
+  static UUID(): string {
+    const currentTimestamp: number = system.currentTick;
+    return "xxxxxxxx-xxxx-4xxx-yxxx-zxxxxxxx".replace(
+      /[xyz]/g,
+      (args: string) => {
+        const random: number = (Math.random() * 16) | 0;
+        const value: number = args === "x" ? random : (random & 0x3) | 0x8;
+        if (args === "z") {
+          return value.toString(16) + currentTimestamp.toString(16).slice(-4);
+        }
+        return value.toString(16);
+      }
+    );
+  }
+}

package/src/api/RandomEvent.ts

@@ -0,0 +1,71 @@
+import { OccultusSDKError } from "@occultus/core";
+import { Percent } from "@occultus/math-api";
+import { Random } from "./Random";
+import { EventListData } from "../interface/EventListData";
+import { EventListResult } from "../interface/EventListResult";
+
+export class RandomEvent {
+  /**
+   * @param chance 触发该事件的概率，必须为百分数，例如 0.5 表示 50%
+   * @param event
+   */
+  constructor(
+    public chance: number,
+    public event: () => void
+  ) {
+    if (!Percent.check(chance)) {
+      throw new OccultusSDKError(`Invaild chance!`, "Random Event");
+    }
+  }
+  /**
+   * 调用事件，根据给定的概率决定是否触发事件
+   *
+   * @return 一个布尔值，表示是否触发了事件
+   */
+  call(): boolean {
+    const result = Random.decimal(1) <= this.chance;
+    if (result) {
+      this.event();
+    }
+    return result;
+  }
+}
+
+export class EventList {
+  /**
+   * @param data 该事件列表的数据
+   */
+  constructor(public data: EventListData[]) {}
+  /**
+   * 调用事件，根据给定的权重决定触发何种事件
+   *
+   * @returns 该函数运行的结果
+   */
+  call(): EventListResult {
+    const weights: number[] = [];
+    this.data.forEach((data) => {
+      weights.push(data.weight);
+    });
+    weights.sort((a, b) => a - b);
+    const cumulativeWeights: number[] = [];
+    let sum = 0;
+    for (const weight of weights) {
+      sum += weight;
+      cumulativeWeights.push(sum);
+    }
+    const num = Random.integer(0, sum);
+    for (let i = 0; i < cumulativeWeights.length; i++) {
+      if (num < cumulativeWeights[i]) {
+        if (this.data[i]?.event) {
+          this.data[i]?.event?.();
+        }
+        return {
+          weightSum: sum,
+          weightRand: num,
+          dataIndex: i,
+        };
+      }
+    }
+    throw new OccultusSDKError("Cannot find the event to call!", "Event List");
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./api/Random"
+export * from "./api/RandomEvent"
+export * from "./interface/EventListData"
+export * from "./interface/EventListResult"

package/src/interface/EventListData.ts

@@ -0,0 +1,14 @@
+/**
+ * {@link withWeightChance} 的权重和事件数据
+ */
+
+export interface EventListData {
+  /**
+   * 触发该事件的权重
+   */
+  weight: number;
+  /**
+   * 要触发的事件
+   */
+  event?: () => void;
+}

package/src/interface/EventListResult.ts

@@ -0,0 +1,18 @@
+/**
+ * {@link withWeightChance} 的触发结果
+ */
+
+export interface EventListResult {
+  /**
+   * 权重之和
+   */
+  weightSum: number;
+  /**
+   * 生成的随机数
+   */
+  weightRand: number;
+  /**
+   * 被触发的事件索引
+   */
+  dataIndex: number;
+}

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": "node16",
+    "esModuleInterop": true,
+    "module": "node16",
+    "outDir": ".",
+    "removeComments": true,
+    "newLine": "lf",
+    "resolveJsonModule": true
+  }
+}