KairoRouter

import { router } from '@kairo-js/router'

以 router 单例形式导出的类。提供 kairo-router 的核心功能：插件初始化、API 调用、事件订阅等。

属性

afterEvents

readonly afterEvents: KairoAfterEvents

订阅 after 事件。

---

beforeEvents

readonly beforeEvents: KairoBeforeEvents

订阅 before 事件。

---

currentTick

readonly currentTick: number

自激活以来的当前 tick 计数（getter）。

---

systemInfo

readonly systemInfo: KairoContext

插件上下文信息（getter）。

---

方法

• clearRun
• delete
• emit
• getAddonId
• has
• init
• load
• request
• runInterval
• runTimeout
• save
• send
• waitForWorldLoad

clearRun

clearRun(runId: number): void

取消由 runInterval() 或 runTimeout() 创建的定时任务。

参数

• runId: number

  要取消的任务 ID。

返回值： void

---

emit

emit(eventName: string, payload?: unknown): void

触发一个自定义事件。将被传递给通过 AddonEventRegistry.on() 订阅的处理器。

参数

• eventName: string

  要触发的事件名称。

• payload: unknown

  附加到事件的数据（可选）。

返回值： void

---

getAddonId

getAddonId(): string | undefined

返回本插件的 addonId。在插件注册之前返回 undefined。

返回值： string | undefined

---

init

init(properties: AddonProperties, options?: RouterInitOptions): void

初始化插件。如果 properties.dependencies 中未包含 "kairo"，将抛出 KairoRouterInitError。

参数

• properties: AddonProperties

  插件的配置信息。

• options: RouterInitOptions

  初始化选项（可选）。

返回值： void

独立模式

如果必须依赖项仅包含 kairo 和 kairo-database，则在未安装 kairo 的世界中插件会自动激活。详情请参见 RouterInitOptions。

---

request

request<TReturn>(
  targetAddonId: string,
  apiName: string,
  args?: unknown,
  options?: { timeout?: number },
): Promise<TReturn | CanceledResult>

调用 API 并等待结果。timeout 以 tick 为单位，默认为 20 tick。

参数

• targetAddonId: string

  目标插件的 ID。

• apiName: string

  要调用的 API 名称。

• args: unknown

  传递给 API 的参数（可选）。

• options.timeout: number

  超时时间，单位为 tick（默认 20）。

返回值： Promise<TReturn | CanceledResult>

const result = await router.request<{ balance: number }>(
  'economy-addon',
  'economy/getBalance',
  { playerId: 'abc123' },
)

if ('canceled' in result) {
  console.warn('Request cancelled:', result.reason)
} else {
  console.log('Balance:', result.balance)
}

---

runInterval

runInterval(callback: () => void, tickInterval?: number): number

按照给定的 tick 间隔重复执行回调。返回可传递给 clearRun() 的 runId。

参数

• callback: () => void

  要重复执行的函数。

• tickInterval: number

  间隔时间，单位为 tick（可选）。

返回值： number — runId

---

runTimeout

runTimeout(callback: () => void, tickDelay?: number): number

在给定的 tick 延迟后执行一次回调。返回可传递给 clearRun() 的 runId。

参数

• callback: () => void

  要执行一次的函数。

• tickDelay: number

  延迟时间，单位为 tick（可选）。

返回值： number — runId

---

send

send(targetAddonId: string, apiName: string, args?: unknown): void

以即发即忘方式调用 API，不等待响应。若目标插件不存在或未激活，则静默忽略。

参数

• targetAddonId: string

  目标插件的 ID。

• apiName: string

  要调用的 API 名称。

• args: unknown

  传递给 API 的参数（可选）。

返回值： void

router.send('economy-addon', 'onTransaction', { amount: 50 })

---

delete

delete(key: string): Promise<void>

删除指定键的已存储值。需要在 dependencies 或 optionalDependencies 中声明 "kairo-database"。在独立模式下，不执行任何操作并立即 resolve。

参数

• key: string

  要删除的键。

返回值： Promise<void>

---

has

has(key: string, options?: { addonId?: string }): Promise<boolean>

如果指定键存在则返回 true。需要在 dependencies 或 optionalDependencies 中声明 "kairo-database"。在独立模式下，始终返回 false。

参数

• key: string

  要检查的键。

• options.addonId: string

  指定时从其他插件的存储中查找（可选）。

返回值： Promise<boolean>

---

load

load<T = unknown>(key: string, options?: { addonId?: string }): Promise<T | undefined>

从存储中读取值。键不存在时返回 undefined。需要在 dependencies 或 optionalDependencies 中声明 "kairo-database"。在独立模式下，始终返回 undefined。

参数

• key: string

  要读取的键。

• options.addonId: string

  指定时从其他插件的存储中读取（可选）。

返回值： Promise<T | undefined>

---

save

save(key: string, value: unknown): Promise<void>

将值以指定键保存到存储中。需要在 dependencies 或 optionalDependencies 中声明 "kairo-database"。在独立模式下，不执行任何操作并立即 resolve。

参数

• key: string

  存储键。

• value: unknown

  要保存的值。

返回值： Promise<void>

---

waitForWorldLoad

waitForWorldLoad(): Promise<void>

在世界加载完成后 resolve。

返回值： Promise<void>