原创 开源 工具 脚本 Monoceros —— 基于 Fluxon 脚本实现各类工具 1.0.1

[MD]  # Monoceros - Minecraft 服务器机制与玩法平台 > 基于 TabooLib 的跨版本服务器基础设施，覆盖 1.12.2 ~ 26.1.2，以 Fluxon 脚本驱动一切。 [](https://github.com/YsGqHY/Monoceros/releases) [](https://github.com/YsGqHY/Monoceros/issues) --- ## 这是什么？ Monoceros 不是又一个"单点功能插件"。它是一个面向 Minecraft 服务器玩法开发的完整基础设施平台，提供： - 统一的事件监听与分发体系 - 强大的 Fluxon 脚本引擎（替代 Kether） - 可视化动作工作流与属性系统 - 数据包级别的抓包、拦截与覆写 - 客户端幻象、伪方块、伪边界等挥发能力 - 战斗、区域、交互、视觉、会话五大玩法机制 - 全配置驱动，热重载友好，零硬编码 一句话：把你从重复造轮子中解放出来，专注于玩法设计本身。 --- ## 核心能力一览 ### 1. Fluxon 脚本引擎 Monoceros 以 Fluxon 作为统一脚本运行时。所有监听器、命令、调度任务、工作流节点都可以由脚本驱动。 脚本从文件系统加载，支持增量热重载、预编译缓存、SHA-256 变更检测与 FileWatcher 实时监听。 ```fluxon script // script/dispatcher/player-join.fs // 玩家加入时自动执行 print("玩家 ${&?player} 加入了服务器") ``` ```fluxon script // script/action/combat.hit-feedback.fs // 战斗命中反馈 dmg = &?damage ?: 0 print("[战斗] 命中反馈: 伤害=${&dmg}") ``` 系统保留变量：`sender`、`player`、`source`、`scriptId`、`now`、`thread`，脚本中可直接使用。 自动导入 `cc.bkhk.monoceros.*`、`cc.bkhk.monoceros.api.*`、`org.bukkit.*`、`org.bukkit.entity.*`、`org.bukkit.inventory.*`，无需手动 import。 脚本中可直接通过 `static` 访问 Monoceros API（方法已标注 `@JvmStatic`）： ```fluxon script api = static cc.bkhk.monoceros.Monoceros.api() plugin = static cc.bkhk.monoceros.Monoceros.plugin() session = &api.sessions().getOrCreate(&p.getUniqueId()) ``` #### 内建扩展函数 Monoceros 向 Fluxon 运行时注册了 7 类扩展函数，脚本中直接调用，无需 import： | 分类 | 函数 | 说明 | |---|---|---| | JSON | `jsonParse(str)` / `jsonStringify(obj)` / `jsonPretty(obj)` | JSON 解析与序列化 | | HTTP | `httpGet(url)` / `httpPost(url, body)` / `httpRequest(...)` | 异步 HTTP 请求，用 `await` 消费 | | UUID | `uuid()` / `uuidFromString(str)` / `uuidFromName(name)` | UUID 生成与解析 | | 冷却 | `cooldown(key, ms)` / `hasCooldown(key)` / `getCooldown(key)` | 冷却/频率限制 | | 颜色 | `colored(text)` / `uncolored(text)` | 颜色代码转换，支持 `:: colored()` 扩展 | | 日志 | `logInfo(msg)` / `logWarn(msg)` / `logDebug(msg)` / `logError(msg)` | 结构化日志 | | 正则 | `regex(pattern)` / `regexMatch(text, pattern)` / `regexReplace(...)` | 正则匹配与替换 | ### 2. 事件分发系统 告别零散的 `@SubscribeEvent`。Monoceros 建立了统一的 Dispatcher 体系： ```yaml # 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）。 ```yaml # 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. 动作工作流 将复杂逻辑拆解为有序节点链，配置即逻辑： ```yaml # 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） 底层数据包级别的监听、过滤、追踪、拦截与覆写： ```yaml # 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 ``` ```fluxon script // script/debug/packet.trace.fs name = &?packetName ?: "unknown" cls = &?packetClass ?: "" print("[Wireshark] 追踪: ${&name} (${&cls})") ``` - 支持 PacketReceiveEvent 与 PacketSendEvent - 玩家级会话（PacketSession），可按玩家开启/关闭 Tap - 拦截与覆写受全局开关控制（`wireshark.allow-intercept`），默认保守 - 支持字段级覆写（field-set） - 内建 MeteorInjector 抑制器，自动屏蔽外部注入干扰 ### 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 - 上下文隔离：每个玩家独立会话，多机制互不干扰 - API 直达：`Monoceros.api().sessions()` 获取 SessionService，脚本中一行可用 --- ## 命令系统 主命令 `/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，只重载真正变化的文件，不做全量刷新。 命令重载采用延迟注册策略，避免与 Paper 异步命令树构建线程冲突，确保热重载过程零报错。 --- ## 跨版本支持 覆盖 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 上下文变量知识，生成准确的脚本： ```fluxon script // 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 中的分发器、调度、工作流配置格式知识，一次性生成完整方案： 分发器配置： ```yaml # 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 ``` 调度配置： ```yaml # 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 ``` 脚本： ```fluxon script // 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 ``` ```yaml # 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 ``` ```fluxon script // script/debug/entity-spawn.fs name = &?packetName ?: "unknown" print("[调试] 实体生成包: ${&name}") print(" 目标玩家: ${&?player}") print(" 时间戳: ${&?now}") ``` ### 示例 4：设计动作工作流 ``` 用户：帮我做一个新手引导工作流，依次发送欢迎消息、给予物品、播放音效 AI 自动调用 Skill：Monoceros ``` ```yaml # 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你已获得新手礼包，祝你游戏愉快!" ``` ```fluxon script // 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 的脚本体验 - 内建扩展函数库：JSON / HTTP / UUID / 冷却 / 颜色 / 日志 / 正则，开箱即用 - 热重载，不是重启：修改配置和脚本后秒级生效 - 跨版本，不是单版本：一套配置跑遍 1.12.2 到 26.1.2 - 模块化，不是铁板一块：28 个子模块，按需组合，职责清晰 --- ## 链接 - GitHub 仓库：https://github.com/YsGqHY/Monoceros - 问题反馈：https://github.com/YsGqHY/Monoceros/issues - 版本发布：https://github.com/YsGqHY/Monoceros/releases [/MD]