分发器定义

分发器通过 YAML 文件定义，放在插件目录下的 dispatcher/ 文件夹中。每个文件可以包含单个或多个分发器定义。

完整示例

以下是 dispatcher/player-join.yml 的真实示例，当玩家加入服务器时执行欢迎脚本：

resource-version: 1
id: player.join.welcome
listen-event: PlayerJoinEvent
listen-priority: NORMAL
weight: 20
execute:
  route: script
  value: dispatcher.player-join
variables:
  triggerSource: join

字段说明

字段	类型	必填	默认值	说明
id	字符串	否	文件 ID	分发器唯一标识，省略时使用文件名作为 ID
listen-event	字符串	是	—	监听的 Bukkit 事件类名，如 PlayerJoinEvent
listen-priority	枚举	否	NORMAL	事件监听优先级
weight	整数	否	0	同优先级下的排序权重，数值越大越先执行
ignore-cancelled	布尔	否	false	是否忽略已被其他插件取消的事件
before-execute	字符串	否	—	主执行前运行的脚本 ID
after-execute	字符串	否	—	主执行后运行的脚本 ID
execute	字符串/对象	是	—	路由目标，见下方说明
variables	键值对	否	—	预注入到执行上下文中的变量

listen-priority 可选值

LOWEST → LOW → NORMAL → HIGH → HIGHEST → MONITOR

优先级越低越先被 Bukkit 调用。MONITOR 仅用于只读监听，不应在此阶段修改事件。

execute 路由目标

execute 支持两种写法：

简写形式 —— 直接填脚本 ID，默认路由类型为 script：

execute: dispatcher.player-join

完整形式 —— 指定路由类型和目标值：

execute:
  route: script    # script / action / handler
  value: dispatcher.player-join

路由类型	说明
script	执行 Fluxon 脚本
action	执行动作工作流
handler	执行自定义处理器

多定义文件

一个 YAML 文件中可以定义多个分发器，每个顶层键作为一个独立的分发器：

resource-version: 1

player.join.welcome:
  listen-event: PlayerJoinEvent
  weight: 20
  execute: dispatcher.player-join
  variables:
    triggerSource: join

player.quit.cleanup:
  listen-event: PlayerQuitEvent
  weight: 10
  execute: dispatcher.player-quit
  variables:
    triggerSource: quit

这种写法适合将相关的分发器集中管理在同一个文件中。

上下文变量

脚本执行时可以访问以下上下文变量：

• 事件对象 —— 触发的 Bukkit 事件实例
• sender —— 事件关联的发送者（通常是玩家）
• variables 中定义的所有预注入变量