Starock Random API

该 API 提供了生成随机事件与随机数、随机 UUID 的功能。

EventList

EventList 是一个用于管理加权事件列表的类，它允许根据权重随机触发事件，并返回触发结果的相关信息：

// 创建事件列表数据
const eventData: EventListData[] = [
  { weight: 10, event: () => console.log("事件1触发") },
  { weight: 30, event: () => console.log("事件2触发") },
  { weight: 60, event: () => console.log("事件3触发") }
];

// 创建事件列表实例
const eventList = new EventList(eventData);

// 调用事件
const result = eventList.call();
console.log(`触发事件索引: ${result.dataIndex}, 权重总和: ${result.weightSum}, 随机权重值: ${result.weightRand}`);

constructor(public data: EventListData[])

创建一个新的 EventList 实例

• 参数:
  • data: EventListData[] - 事件列表数据，包含事件及其对应的权重

call(): EventListResult

• 描述: 调用事件，根据给定的权重决定触发何种事件
• 返回值: EventListResult - 包含事件触发结果的对象
  • weightSum: number - 所有事件权重的总和
  • weightRand: number - 随机生成的权重值
  • dataIndex: number - 被触发事件在数组中的索引
• 异常: 如果找不到要调用的事件，会抛出 OccultusSDKError 异常

Random

Random 是一个提供随机数和 UUID 生成功能的工具类，包含生成随机整数、随机小数和 UUID 的静态方法：

// 生成 1 到 10 之间的随机整数（包含 1 和 10）
const randomInt = Random.integer(10, 1);
console.log(randomInt); // 可能输出: 7

// 生成 1 到 10 之间的随机整数（不包含 10）
const randomIntExclusive = Random.integer(10, 1, false);
console.log(randomIntExclusive); // 可能输出: 5

// 生成 1.0 到 10.0 之间的随机小数，保留 3 位小数
const randomDecimal = Random.decimal(10, 1, 3);
console.log(randomDecimal); // 可能输出: 3.142

// 生成一个 UUID
const uuid = Random.UUID();
console.log(uuid); // 可能输出: "a1b2c3d4-e5f6-4g7h-i8j9-k0l1m2n3o4p5"

integer(max: number, min = 0, inclusive = true): number

生成指定范围内的随机整数

• 参数:
  • max: number - 最大值，小数部分将被解析为整数
  • min: number (可选，默认为 0) - 最小值，小数部分将被解析为整数
  • inclusive: boolean (可选，默认为 true) - 生成的随机数是否包含最小值和最大值
• 返回值: number - 在最小值和最大值之间的一个随机整数
• 异常: 如果 max < min，则抛出 RangeError

decimal(max: number, min = 0, fixed = 2, inclusive = true): number

生成指定范围内的随机小数

• 参数:
  • max: number - 最大值，小数部分将被解析为整数
  • min: number (可选，默认为 0) - 最小值，小数部分将被解析为整数
  • fixed: number (可选，默认为 2) - 保留的小数位数
  • inclusive: boolean (可选，默认为 true) - 生成的随机数是否包含最小值和最大值
• 返回值: number - 在最小值和最大值之间的一个随机小数
• 异常: 如果 max < min，则抛出 RangeError

UUID(): string

生成一个 UUID

• 返回值: string - 一个字符串形式的 UUID

RandomEvent

RandomEvent是一个用于处理概率性事件触发的类，它允许根据设定的概率决定是否执行特定的事件函数：

// 创建一个有 30% 概率触发的事件
const randomEvent = new RandomEvent(0.3, () => {
  console.log("事件被触发了！");
});

// 尝试触发事件
const triggered = randomEvent.call();
console.log(`事件是否被触发: ${triggered}`);

constructor(public chance: number, public event: () => void)

创建一个新的 RandomEvent 实例

• 参数:
  • chance: number - 触发该事件的概率，必须为百分数，例如 0.5 表示 50%
  • event: () => void - 当事件被触发时执行的回调函数
• 异常: 如果提供的概率值无效，会抛出 OccultusSDKError 异常

call(): boolean

调用事件，根据给定的概率决定是否触发事件

• 返回值: boolean - 表示是否触发了事件的布尔值
  • true: 事件被触发并执行
  • false: 事件未被触发

支持版本

本 API 支持任意可以运行 Script API v2.0.0+ 的游戏版本，包括：

• 1.21.90；
• 1.21.100；
• 1.21.110；
• 以及更多……

注意：本包理论上可以在部分更旧的版本上运作，但未经过严格的测试。

协议

本项目使用 MIT License 授权：

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.