模组插件数据包光影资源包整合包软件汉化
设置
Monoceros —— 基于 Fluxon 脚本实现各类工具
Monoceros —— 基于 Fluxon 脚本实现各类工具

Monoceros —— 基于 Fluxon 脚本实现各类工具

基于 TabooLib 的跨版本 Minecraft 服务器机制平台，提供事件分发、脚本驱动、数据包监听与玩法工作流能力

实用工具游戏机制管理
00a day ago

基本信息

我的世界Java版本

26.1.x
1.21.x
1.20.x
1.19.x
1.18.x
1.17.x
1.16.x
1.15.x
1.14.x
1.13.x
1.12.2

平台

Bukkit
Folia
\n \n \n \n \n Paper
\n \n \n \n \n \n \n \n \n \n \n Purpur
Spigot

运行环境

服务端

其他链接

反馈问题 查看源码

创作者

Kether
Kether Member

详情信息

许可证 MIT
发布于 2026-04-23
更新于 2026-04-23

banner

Monoceros - Minecraft 服务器机制与玩法平台

基于 TabooLib 的跨版本服务器基础设施，覆盖 1.12.2 ~ 26.1.2，以 Fluxon 脚本驱动一切。

GitHub GitHub Issues

这是什么？

Monoceros 不是又一个"单点功能插件"。它是一个面向 Minecraft 服务器玩法开发的完整基础设施平台，提供：

  • 统一的事件监听与分发体系
  • 强大的 Fluxon 脚本引擎（替代 Kether）
  • 可视化动作工作流与属性系统
  • 数据包级别的抓包、拦截与覆写
  • 客户端幻象、伪方块、伪边界等挥发能力
  • 战斗、区域、交互、视觉、会话五大玩法机制
  • 全配置驱动，热重载友好，零硬编码

一句话：把你从重复造轮子中解放出来，专注于玩法设计本身。

核心能力一览

1. Fluxon 脚本引擎

Monoceros 以 Fluxon 作为统一脚本运行时。所有监听器、命令、调度任务、工作流节点都可以由脚本驱动。

脚本从文件系统加载，支持增量热重载、预编译缓存、SHA-256 变更检测与 FileWatcher 实时监听。

// script/dispatcher/player-join.fs
// 玩家加入时自动执行
print("玩家 ${&?player} 加入了服务器")

// script/action/combat.hit-feedback.fs
// 战斗命中反馈
dmg = &?damage ?: 0
print("[战斗] 命中反馈: 伤害=${&dmg}")

系统保留变量：sender、player、source、scriptId、now、thread，脚本中可直接使用。

自动导入 org.bukkit.*、org.bukkit.entity.*、org.bukkit.inventory.*，无需手动 import。

2. 事件分发系统

告别零散的 @SubscribeEvent。Monoceros 建立了统一的 Dispatcher 体系：

# dispatcher/player-join.yml
id: player.join.welcome
listen-event: PlayerJoinEvent
listen-priority: NORMAL
weight: 20
execute:
  route: script
  value: dispatcher.player-join
variables:
  triggerSource: join
  • 按"事件类型 -> 优先级 -> 权重"三级路由
  • 同优先级下多个处理器按权重排序
  • 支持动态注册、动态注销、热重载后自动重建分发表
  • 5 阶段 Pipeline：initPrincipal -> initVariables -> filter -> afterFilter -> postprocess
  • 内建冷却（Baffle）、列表过滤、玩家反射提取等 Pipeline
  • 路由目标支持：脚本 / 动作工作流 / 自定义 Handler

对于 Bukkit 原生没有提供事件的状态（如玩家护甲变更），Monoceros 通过状态探针（StateProbe）自动补齐。

3. 调度系统

支持四种调度类型：延迟（DELAY）、周期（PERIODIC）、Cron 表达式（CRON）、条件触发（CONDITIONAL）。

# schedule/broadcast.yml
id: world.tick.broadcast
type: periodic
delay: 20t
period: 200t
auto-start: true
async: false
max-runs: -1
execute:
  route: script
  value: schedule.world.tick.broadcast
variables:
  triggerSource: periodic
  • 支持最大执行次数、最大持续时间限制
  • 支持暂停 / 恢复 / 停止，运行态完全可控
  • 支持 prototype 模式（多实例并行）
  • 发送者选择器：CONSOLE / ONLINE_PLAYER / PLAYER / WORLD / RANGE / AREA
  • 生命周期脚本：onStart / onStop / onPause / onResume

4. 动作工作流

将复杂逻辑拆解为有序节点链，配置即逻辑：

# workflow/action/combat-hit.yml
id: combat.hit-feedback
failure-policy: continue
nodes:
  - id: log-hit
    type: log
    message: "战斗命中反馈触发"
  - id: set-damage
    type: set
    key: damage
    value: 10
  - id: run-script
    type: script
    script: action.combat.hit-feedback

内建 15 种动作节点：

节点 说明
script 调用 Fluxon 脚本
set 设置上下文变量
log 日志输出
wait 延迟执行（tick）
branch 条件分支（脚本求值 + then/else）
loop 循环遍历
sound 播放音效
tellraw 发送富文本消息
regex 正则匹配与捕获组提取
try-catch 异常捕获与降级
input 等待玩家输入（聊天捕获 + 超时）
if-else 条件分支
math 数学运算（abs/ceil/floor/round/sqrt/pow/min/max/random/sin/cos/tan/log）
coerce 数值范围约束
dispatch 分发到子工作流/脚本/分发器

控制流支持 Continue、Delay（异步延续不阻塞）、Branch（条件分支）、Break（中断）。

5. 数据包监听（Wireshark）

底层数据包级别的监听、过滤、追踪、拦截与覆写：

# wireshark/example.yml
id: example.packet.trace
direction:
  - send
  - receive
matcher:
  type: packet-name
  value: PacketPlayOutChat
tracking: true
parse: true
intercept: false
route:
  type: script
  value: debug.packet.trace

// script/debug/packet.trace.fs
name = &?packetName ?: "unknown"
cls = &?packetClass ?: ""
print("[Wireshark] 追踪: ${&name} (${&cls})")
  • 支持 PacketReceiveEvent 与 PacketSendEvent
  • 玩家级会话（PacketSession），可按玩家开启/关闭 Tap
  • 拦截与覆写受全局开关控制（wireshark.allow-intercept），默认保守
  • 支持字段级覆写（field-set）

6. 挥发能力（Volatility）

客户端侧的幻象效果，不修改服务端真实状态：

  • 伪方块：sendBlockChange / sendBlockChanges
  • 世界边界：静态边界 / 动态渐变边界
  • 实体元数据：发光、隐身、姿态、血量、骑乘
  • 幻象会话：通过 IllusionKey(viewerId, namespace, targetId) 精准标识每个幻象效果，支持多机制同时写入、按 key 精准回滚

7. 属性系统

统一的属性读写框架，覆盖 Bukkit 核心对象：

  • Location：x/y/z/yaw/pitch/world/block/chunk/direction（可读写）
  • Vector：完整 3D 向量数学（构造/算术/几何/旋转）
  • Entity/LivingEntity/Player：全属性链式访问与写入
  • World：时间/天气/难度/玩家列表
  • ItemStack：类型/数量/附魔/标志/耐久
  • Block：类型/光照/生物群系/数据
  • Event：通用事件属性 + 15 种具体事件的专属属性访问器

六大扩展域

实体域

实体操作：伤害、治疗、传送、药水效果、属性切换、装备设置。 位置操作：构建、克隆、修改、四则运算、距离计算。 向量操作：完整 3D 数学库，包括归一化、点积、叉积、旋转。

事件域

事件控制：取消、忽略、属性写入、回复消息。 异步等待：event.wait 可异步等待指定事件触发（带超时）。

幻象域

  • 发光效果（支持回滚）
  • 视觉警告（Title + Subtitle + ActionBar + 世界边界压迫）
  • 呼吸式警告（正弦波变化）
  • 假方块、伪血量、客户端全息文字
  • 幻象上下文切换

物品域

物品全生命周期：构建、修改名称/Lore/附魔/标志/耐久/颜色/标签。 物品操作：消耗、销毁、掉落、给予。 背包操作：检查、计数、查找、切换、取出。 药水操作：查询/设置/移除/清空。

记忆域

6 种作用域的键值存储：GLOBAL / PLAYER / ENTITY / WORKFLOW / SCRIPT / SESSION。 支持 TTL 过期（3000ms / 3s），自动过期检测，线程安全。

目标域

9 种目标选取方式：自身、世界、全服、半径、立方体、最近 N 个、环形、指定玩家、视线选取。 目标操作：按类型过滤、按脚本条件过滤、逐个执行子工作流。

五大玩法机制

战斗机制

  • 冷却管理：setCooldown / getCooldownRemaining / hasCooldown
  • 连击追踪：recordHit（返回连击数）/ getComboCount / resetCombo
  • 状态叠层：apply（支持 stacks/maxStacks + TTL）/ remove / get
  • 技能执行器：5 阶段执行链 CONDITION -> WINDUP -> EXECUTE -> RECOVERY -> COOLDOWN

区域机制

  • 区域定义：Cuboid（立方体）/ Sphere（球体）
  • 区域事件：进入 / 离开 / 驻留（可配置检测间隔）
  • 区域效果：Buff/Debuff 自动应用
  • 区域脚本：onEnter / onLeave / onStay

交互机制

  • 交互类型：右键 / 左键 / 潜行右键 / 潜行左键 / 潜行切换
  • 材料过滤：按物品类型触发
  • 视线锁定：getLookAtTarget 获取视线目标实体与距离
  • 冷却控制：按交互定义独立冷却

视觉机制

  • BossBar：创建 / 更新 / 显示 / 隐藏（支持颜色与样式）
  • ActionBar：带持续时间的消息推送
  • Title：fadeIn / stay / fadeOut 完整控制
  • 消息队列：优先级排序，避免消息覆盖

会话机制

  • 玩家会话：get/set/remove/has，支持快照与恢复
  • 机制参与：joinMechanic / leaveMechanic / getActiveMechanics
  • 上下文隔离：每个玩家独立会话，多机制互不干扰

命令系统

主命令 /monoceros（别名 /mono），权限前缀 monoceros.command。

/mono reload [service]        重载所有服务或指定服务
/mono version                 显示版本号
/mono debug                   切换调试模式
/mono status                  显示所有服务状态与环境画像
/mono selfcheck               运行自检，输出问题与建议

/mono script run <id>         执行脚本
/mono script stop <id>        停止脚本任务
/mono script task list        列出活跃任务
/mono script reload           重载脚本定义
/mono script preheat          预热所有脚本
/mono script stats            显示缓存统计

/mono schedule start <id>     启动调度
/mono schedule pause <id>     暂停调度
/mono schedule resume <id>    恢复调度
/mono schedule stop <id>      停止调度
/mono schedule detail [id]    查看调度详情（含可交互操作按钮）

/mono dispatcher reload       重载分发器
/mono dispatcher enable <id>  启用分发器
/mono dispatcher disable <id> 禁用分发器

命令定义同样支持配置化，参数类型涵盖 STRING / INT / DOUBLE / BOOLEAN / PLAYER / WORLD / MATERIAL / SCRIPT_ID。

配置驱动，热重载友好

所有核心功能均通过 YAML 配置驱动，修改后 /mono reload 即时生效：

plugins/Monoceros/
├── config.yml                 # 主配置
├── dispatcher/                # 事件分发器定义
│   └── player-join.yml
├── schedule/                  # 调度任务定义
│   └── broadcast.yml
├── wireshark/                 # 数据包 Tap 定义
│   └── example.yml
├── workflow/
│   └── action/                # 动作工作流定义
│       └── combat-hit.yml
├── script/                    # Fluxon 脚本
│   ├── dispatcher/
│   ├── schedule/
│   ├── action/
│   ├── command/
│   ├── debug/
│   └── shared/
└── lang/                      # 国际化语言文件
    ├── zh_CN.yml
    └── en_US.yml

文件变更检测基于 SHA-256 + FileWatcher，只重载真正变化的文件，不做全量刷新。

跨版本支持

覆盖 Minecraft 1.12.2 ~ 26.1.2，版本差异通过模块化处理：

  • module-legacy-api：旧版本 Material、NBT、文本兼容
  • module-modern：Data Components、新版 ItemMeta
  • module-java17 / module-java21：Java 版本专属依赖隔离
  • NMS 差异通过 TabooLib nmsProxy 桥接，业务层零版本判断

运维与诊断

  • /mono selfcheck：自动检测配置错误、缺失依赖、版本不兼容
  • /mono diag dump：导出完整运行态信息
  • /mono diag cache：导出缓存命中率与编译统计
  • DiagnosticLogger：统一诊断日志，debug 模式可开关
  • 重载报告：每次 reload 输出 loaded / updated / failed / costMs

AI 辅助开发示例

Monoceros 提供了 Monoceros AI Skill，可在支持 Skill 的 AI 编程助手（如 Kiro）中直接调用。该 Skill 内置了 Monoceros 全部配置格式、机制服务、Fluxon 脚本语法的完整知识库，让 AI 能够准确生成配置与脚本，而不是靠猜。

Skill 文件可在仓库中自取：https://github.com/YsGqHY/Monoceros/tree/master/.claude/skills

使用方式：将 Skill 文件放入你的 AI 编程助手对应目录，在对话中向 AI 提出需求，AI 会自动调用 Monoceros Skill 获取知识后生成结果。

示例 1：编写 Fluxon 脚本

用户：帮我写一个 Fluxon 脚本，当玩家血量低于 30% 时给予发光效果并发送警告

AI 自动调用 Skill：Monoceros

AI 基于 Skill 提供的 Fluxon 语法与 Monoceros 上下文变量知识，生成准确的脚本：

// script/mechanic/low-health-warning.fs
health = &?player.getHealth()
maxHealth = &?player.getMaxHealth()
ratio = &health / &maxHealth

if (&ratio < 0.3) {
    &?player.setGlowing(true)
    &?player.sendMessage("&c警告: 你的血量已低于 30%!")
} else {
    &?player.setGlowing(false)
}

示例 2：生成完整的配置方案

用户：帮我做一个区域守卫机制，玩家进入指定区域后每 3 秒扣血，离开后恢复

AI 自动调用 Skill：Monoceros

AI 基于 Skill 中的分发器、调度、工作流配置格式知识，一次性生成完整方案：

分发器配置：

# dispatcher/region-guard-enter.yml
id: region.guard.enter
listen-event: PlayerMoveEvent
listen-priority: NORMAL
weight: 10
execute:
  route: action-workflow
  value: region.guard.damage-loop
rules:
  - type: script
    value: |
      loc = &?player.getLocation()
      x = &loc.getX()
      z = &loc.getZ()
      &x > 100 && &x < 200 && &z > 100 && &z < 200
variables:
  triggerSource: region-enter

调度配置：

# schedule/region-guard-tick.yml
id: region.guard.tick
type: periodic
delay: 0t
period: 60t
auto-start: true
async: false
execute:
  route: script
  value: mechanic.region-guard.tick

脚本：

// script/mechanic/region-guard.tick.fs
// 每 3 秒对区域内玩家造成 2 点伤害
players = static org.bukkit.Bukkit.getOnlinePlayers()

for p in &players {
    loc = &p.getLocation()
    x = &loc.getX()
    z = &loc.getZ()
    if (&x > 100 && &x < 200 && &z > 100 && &z < 200) {
        &p.damage(2.0)
        &p.sendMessage("&c你正在受到区域守卫的伤害!")
    }
}

示例 3：调试数据包

用户：帮我写一个 Wireshark 配置，追踪所有发给玩家的实体生成包

AI 自动调用 Skill：Monoceros

# wireshark/entity-spawn-trace.yml
id: debug.entity.spawn
direction:
  - send
matcher:
  type: packet-name
  value: PacketPlayOutSpawnEntity
tracking: true
parse: true
intercept: false
route:
  type: script
  value: debug.entity-spawn

// script/debug/entity-spawn.fs
name = &?packetName ?: "unknown"
print("[调试] 实体生成包: ${&name}")
print("  目标玩家: ${&?player}")
print("  时间戳: ${&?now}")

示例 4：设计动作工作流

用户：帮我做一个新手引导工作流，依次发送欢迎消息、给予物品、播放音效

AI 自动调用 Skill：Monoceros

# workflow/action/newbie-guide.yml
id: newbie.guide
failure-policy: continue
nodes:
  - id: welcome-title
    type: tellraw
    message: "&6&l欢迎来到服务器!"
  - id: wait-a-bit
    type: wait
    ticks: 40
  - id: give-item-script
    type: script
    script: action.newbie.give-starter-kit
  - id: play-sound
    type: sound
    sound: ENTITY_PLAYER_LEVELUP
    volume: 1.0
    pitch: 1.0
  - id: guide-message
    type: tellraw
    message: "&a你已获得新手礼包，祝你游戏愉快!"

// script/action/newbie.give-starter-kit.fs

// 给予新手套装
inv = &?player.getInventory()
sword = new org.bukkit.inventory.ItemStack(static org.bukkit.Material.IRON_SWORD)
meta = &sword.getItemMeta()
&meta.setDisplayName("&b新手之剑")
&meta.setLore(["&7专为新手打造"])
&sword.setItemMeta(&meta)

food = new org.bukkit.inventory.ItemStack(static org.bukkit.Material.COOKED_BEEF, 16)

&inv.addItem(&sword, &food)
&?player.sendMessage("&a已发放新手礼包!")

快速开始

  1. 将 Monoceros 插件放入 plugins/ 目录
  2. 启动服务器，插件自动生成默认配置与示例文件
  3. 编辑 dispatcher/、schedule/、script/ 等目录下的配置文件
  4. 使用 /mono reload 热重载，即时生效
  5. 使用 /mono status 查看服务状态，/mono selfcheck 排查问题

为什么选择 Monoceros？

  • 不是功能插件，是玩法基础设施：你不需要为每个玩法写一个插件
  • 配置驱动，不是代码驱动：策划和开发都能参与玩法设计
  • Fluxon 脚本，不是 Kether：更现代、更强大、更接近 Kotlin 的脚本体验
  • 热重载，不是重启：修改配置和脚本后秒级生效
  • 跨版本，不是单版本：一套配置跑遍 1.12.2 到 26.1.2
  • 模块化，不是铁板一块：28 个子模块，按需组合，职责清晰

链接