跳到主要内容

命令定义

Monoceros 会扫描 command/ 目录下的 .yml 和 .yaml 文件，把它们编译成真正可执行的服务端命令。

支持两种文件组织方式​

单定义文件​

一个文件只定义一个命令。

id: example.admin
aliases:
  - exadmin
permission: monoceros.example.admin
permission-message: "&c你没有权限执行此命令。"
root:
  type: literal
  name: example
  children:
    - type: literal
      name: reload
      route:
        type: script
        value: command.example.reload

多定义文件​

一个文件里放多个命令定义，每个顶层 key 都是一条命令。

admin:
  id: example.admin
  root:
    type: literal
    name: example

player:
  id: example.player
  root:
    type: literal
    name: play

如果你的命令比较多，按模块拆成多定义文件会更好维护。

顶层字段​

字段类型说明
idString命令定义 ID，建议全局唯一
aliasesList<String>命令别名列表
permissionString执行该命令所需权限
permission-messageString权限不足时返回的提示
rootObject命令树根节点

节点类型​

命令树由两种节点组成：

literal​

字面量节点，适合写固定命令词，例如 reload、debug、start。

argument​

参数节点，适合接收动态输入，例如玩家名、脚本 ID、材质名、数字等。

节点公共字段​

字段类型说明
typeStringliteral 或 argument
nameString当前节点名称
routeObject命中此节点后执行的路由
childrenList子节点列表

参数节点额外字段​

参数节点需要再配置一个 argument 对象：

- type: argument
  name: scriptId
  argument:
    type: SCRIPT_ID
    required: true
    suggest: script-id

更多参数类型请继续看 ./arguments.md。

文件变更后的行为​

Monoceros 的命令系统支持增量热重载：

  • 新增文件 → 自动注册新命令
  • 修改文件 → 重新编译并更新命令
  • 删除文件 → 自动注销对应命令

这套逻辑由 command/ 目录的文件监听器和增量映射关系一起完成。