脚本定义
脚本定义文件是 script/ 目录下的 YAML 文件，每个文件描述一个可执行脚本。
文件 ID 规则
脚本 ID 默认从文件的相对路径推导：去掉扩展名，将 / 替换为 .。
| 文件路径 | 推导出的 ID |
|---|---|
script/hello.yml | hello |
script/example/hello.yml | example.hello |
script/combat/damage/calc.yml | combat.damage.calc |
你也可以在定义中通过 id 字段手动指定，覆盖自动推导的值。
完整字段
id: example.hello
enabled: true
preheat: false
async-allowed: true
timeout-ms: 0
tags:
- example
metadata:
author: test
parameters:
player: Player
amount: Double
condition: check.permission
deny: notify.no-permission
functions:
helper: example.helper-script
on-timeout: notify.timeout
on-exception: notify.error
return-conversion: String
source:
type: fluxon
content: |
print "Hello, world!"
字段说明
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
id | String | 从文件路径推导 | 脚本唯一标识 |
enabled | Boolean | true | 是否启用此脚本 |
preheat | Boolean | false | 是否在加载时预编译（而非首次执行时编译） |
async-allowed | Boolean | true | 是否允许异步执行 |
timeout-ms | Long | 0 | 执行超时时间（毫秒），0 表示不限制 |
tags | Set<String> | 空 | 分类标签，用于筛选和管理 |
metadata | Map | 空 | 任意键值对元数据 |
parameters | Map | 空 | 参数声明，格式为 参数名: Applicative 类型名 |
condition | String | 无 | 前置条件脚本 ID，返回 false 时拒绝执行 |
deny | String | 无 | 条件不满足时执行的脚本 ID |
functions | Map | 空 | 自定义函数映射，格式为 函数名: 脚本 ID |
on-timeout | String | 无 | 超时回调脚本 ID |
on-exception | String | 无 | 异常回调脚本 ID |
return-conversion | String | 无 | 返回值类型转换（Applicative 类型名） |
source.type | String | fluxon | 脚本类型 |
source.content | String | 无 | 脚本内容（内联 Fluxon 代码） |
关于 Applicative 类型名
parameters 和 return-conversion 里出现的类型名，来自 Monoceros 的 Applicative 转换系统。
如果你想进一步理解这些类型名是怎么注册、怎么转换的，可以继续看 ../api/applicative.md。
前置条件与拒绝回调
你可以通过 condition 指定一个前置条件脚本。执行前会先运行该脚本，如果返回 false，则主脚本不会执行，转而执行 deny 指定的脚本（如果配置了的话）。
condition: check.vip-level
deny: notify.vip-required
超时与异常处理
timeout-ms设置执行超时，超时后自动终止并触发on-timeout回调- 执行过程中抛出异常时触发
on-exception回调
这两个回调都是可选的，不配置则静默处理。