OOCore¶
喵托邦 / Meowopia OO 系列的平台前置，归入基础（Core）。 OOCore 统一管理模块身份、运行能力、生命周期与服务端适配，让各个 OO 插件保持独立功能，同时能够安全组合。
它不是玩法插件，也不提供独立的网页后台、窗口编辑器或客户端画面。只安装 OOCore 不会自动获得聊天、音乐、菜单或游戏内容；需要另外安装对应产品。
它解决什么问题¶
OOCore 为已接入的 OO 插件提供统一的平台能力，让模块在运行前确认所需依赖，并在停止时释放自己的任务、服务和访问权限。业务玩法与可视化管理仍由对应产品负责。
已实现功能 / Implemented¶
以下能力已随 OOCore 1.7.3 正式版交付。部署验证基线为 Paper 26.2-92 与 Java 25；这不表示所有服务端、业务插件组合或真实玩家负载都已验收。需要其他插件调用的能力，只有该插件完成正式接入后才会发挥作用。
| 已发布能力 | 用户实际可以做什么 | 必要条件 / 边界 |
|---|---|---|
| 模块依赖与能力检查 | 启动时发现缺失的必要依赖或平台能力，避免不兼容模块盲目运行 | 业务插件按正式接口声明要求；不是按插件版本号完全相等来判断 |
/oo 统一入口与 Core 诊断 |
使用已注册的插件命令；管理员查看 Core 版本、健康状态、适配器和模块信息 | Core 详情需要查看或管理权限；业务命令遵守各插件自身规则 |
| 模块所属的任务与服务 | 已结束的一次性任务及时释放登记；模块停止时撤销相应任务和服务访问 | 对已接入 Core 生命周期的资源有效，不能代替第三方插件清理所有资源 |
| 托管文件存储与服务器 UID | 保存模块数据与持久服务器标识；限制超大读取并保持旧数据格式 | 通过认证模块会话访问；写入仍同步，托管文件不要手改 |
| 平台基础接口 | 接入插件可使用文本、标识、实体/物品和基础物品数据；消息通道仅提供能力元数据 | 以当前适配器实际提供的能力为准；不等于任意底层封包支持 |
| 安全默认配置 | 默认关闭旧的全局存储入口，限制普通玩家读取 Core 详情 | legacy-storage.enabled 保持 false；需要兼容旧插件时先阅读风险说明 |
未实现功能 / Not implemented¶
- 尚未提供：异步存储与事务型数据迁移。 当前写入不会自动进入后台队列，也没有可供服主调用的事务迁移、自动回滚工具；高频写盘仍需要业务插件控制预算。
- 仍待验证：普遍改善 TPS/MSPT 的性能收益。 已修复任务登记积累，但长 tick 尚未完成归因；不能把本版当作解决所有卡顿的一键优化工具。
- 部分覆盖：更广的服务端运行验证。 Folia 调度适配已实现，但尚未完成本轮 Folia 实服验收；26.1/26.1.2 的识别规则不构成当前 JAR 可在这些版本安装的保证。Minecraft 26.3 与 Java 26 也不属于已验收部署组合。
- 当前不可用：raw packet 能力。 1.7.3 的消息通道接口仅描述能力，不提供绑定插件身份的通道注册、发送或接收功能；任意底层封包能力也不可用。
Core 的独立网页后台、窗口编辑器和业务玩法不是待补的 Core 功能；它们由对应产品负责。对外变量/占位符的当前状态见变量与占位符。
未来计划 / Roadmap¶
下一目标为 1.8.0，尚未发布；当前正式版仍为 1.7.3。目标包括已批准的任务、内存与存储优化、异步存储与背压、由 Core 统一承担的 Java 21 / 旧 Paper 兼容、只读属性与原有连接通信，以及实际业务联动验证。隔离环境的兼容试验不是正式 Java 21 安装包，也不代表其他平台组合已获支持；当前部署基线保持 Paper 26.2-92 / Java 25。
- 优先继续性能定位：使用可比较的负载检查内存分配、存活对象、GC 暂停与 MSPT 尾部尖峰，再决定后续优化；不先承诺节省比例或加速幅度。
- 改进存储扩展能力：规划有预算与背压的异步路径，以及带迁移、恢复边界的数据演进方案；必须保留当前持久化保障与同步接口语义，不能靠提前返回制造“更快”的假象。
- 逐项扩大兼容验证：在对应上游构建可用时分别评估 Minecraft/Paper/Folia 26.3 与 Java 26，并补独立的 Folia 实服验证；验证通过前不扩大已支持范围。
以上是已有规划，不是已交付功能，也没有确定发布日期或新版本承诺。现有插件仍按接口契约、握手与必需能力协商兼容性，不因计划变化要求服主立即升级环境。
版本策略¶
当前正式稳定版为 1.7.3，更新内容见 GitHub Release。仓库与二进制采用受控分发，未获访问权限时请通过下方支持渠道联系作者。
- OOCore 独立发布，不要求与 OOEngine 或其他 OO 插件使用相同版本号。
- 1.7.0 已撤回，禁止安装或回滚到该版本。
- 本版部署验证基线为 Minecraft 26.2 / Paper 26.2-92 / Java 25；不等于所有发行组合都已验证。
- 代码包含 26.1、26.1.2、26.2 的平台识别和适配规则，但本版插件声明的 API 最低版本为 26.2；不能把这些规则当作当前 JAR 在更旧服务端的安装保证。
- Folia 调度适配已实现，但本轮没有 Folia 实服验收；生产部署前需单独确认所用发行版及各业务插件支持情况。
- Minecraft 26.3 与 Java 26 支持仍在规划中，不要据此直接升级生产环境。
OOCore 是 OO 服务端插件的运行时硬依赖。业务插件通过接口契约版本（ABI）、启动握手和所需能力判断兼容性，而不是要求“版本号必须等于 1.7.3”。“最低已验证基线”表示开发者实际验证过的组合；“运行要求”表示启动必须满足的能力。未来兼容版本不应仅因版本号不同而被拒绝，安装时仍应核对对应插件的发布说明。
安装¶
- 准备符合上方部署基线的 Paper 服务端与 Java 25；普通 Bukkit/Spigot 不属于本页的已验证部署范围。
- 停止服务器，并备份完整的
plugins/OOCore/目录（已有安装时）。 - 将正式的
OOCore-1.7.3.jar放入服务器的plugins/目录；移走旧版 Core JAR，不能同时保留两份。 - 按需安装其他 OO 插件。OOCore 自身不需要 OOEngine 或 OOConsole 才能启动。
- 启动服务器，让插件生成配置和托管状态；使用管理员账号执行
/oo core检查启动结果。
需要窗口或可视化管理时，请分别查看 OOEngine 与 OOConsole 的安装要求。不要把 SDK、测试工具或源码包放入服务器插件目录。
配置 / Configuration¶
1.7.3 已提供用户配置文件 plugins/OOCore/config.yml。 首次启动自动生成，包含中英注释。目前唯一用户设置为旧存储兼容开关；没有额外玩法配置或 Core 网页设置界面。
# 修改后完整重启服务器；不支持热重载。
# Restart the server after editing; hot reload is not supported.
legacy-storage:
# 布尔值，默认 false；建议保持关闭。
# Boolean, default false; keep disabled unless temporarily required.
enabled: false
| 设置 | 类型 / 默认值 | 作用与注意事项 |
|---|---|---|
legacy-storage.enabled |
布尔值 / false |
控制已废弃的旧存储兼容入口。设为 true 会允许所有 API 消费者通过该旧入口进行跨模块访问；不是模块白名单。仅在完全信任旧插件且暂时无法迁移时短期启用。 |
填写不带引号的 true 或 false，不要写成字符串 "true"，错误类型会导致启动失败。新插件应使用绑定模块会话的存储入口，不需要打开此开关。关闭开关不会删除旧文件，也不改变新式模块存储的数据格式。
plugins/OOCore/storage/、plugins/OOCore/scoped-storage/ 和 plugins/OOCore/server.uid 是程序管理的状态，不是配置示例；不要手改或为排错随意删除。备份时保留整个目录。安装包中的构建属性不是服务器运行配置。
联系 / Contact¶
- 作者 / Author: zkonikishi
- QQ: 276098266
- Discord: https://discord.gg/KPq2fZHFK
- ifdian
- QQ群 / QQ Group: 1063369777
报告问题时提供 OOCore 与业务插件版本、服务端发行版、复现步骤及相关错误片段。发送日志前移除令牌、密码、玩家隐私和服务器标识；不要公开整份数据目录。
Platform Capability¶
Capability 表示平台实际提供的能力，例如调度、文本与物品。1.7.3 的 OOPlatform.channels() 仅提供通道能力元数据，不代表已具备通道注册或消息收发接口。业务插件应只要求自己真正使用的能力；缺少必需能力时应拒绝启动相应功能，而不是盲目继续运行。
Core 的低层 raw packet 能力仍不可用，也不能把消息通道的能力描述当作可用的收发功能。缺少可选功能时，先检查对应业务插件的要求，不要尝试通过配置伪造能力。
生命周期与泄漏防护¶
任务、服务与存储访问应归属于发起它们的模块。已接入这些接口的模块停止后，其登记和访问被撤销；1.7.3 会及时回收已结束的一次性任务登记，而不是等到停服才释放。
这不意味着 OOCore 能替任意第三方插件清理资源，也不构成对恶意同进程 Java 插件的沙箱。只安装可信来源的插件；业务插件仍需遵守自己的线程、资源与权限约束。
命令¶
以下为正式版 1.7.3 的 Core 命令。玩家在聊天栏输入带 / 的写法；服务器控制台输入时省略开头的 /。Core 不把这些诊断命令限制为仅玩家或仅控制台，但仍检查下列权限。
| 完整语法 | 参数与默认值 | 用途 | 精确权限要求 | 玩家 / 控制台 | 最小示例 |
|---|---|---|---|---|---|
/oo |
无参数；不会自动打开 Core 详情 | 显示版本与命令用法 | 无 Core 权限检查 | 均可 | 玩家：/oo；控制台：oo |
/oo core |
不带子命令时默认显示诊断 | 显示健康状态、适配器、调度类型、服务器标识、模块、服务和能力 | oocore.core.view 或 oocore.admin |
均可，需相应权限 | /oo core |
/oo core admin |
无额外参数 | 显示同一份诊断；不执行修改、重载或清理 | oocore.admin |
均可，需相应权限 | oo core admin |
/oo core about |
无额外参数 | 显示诊断，并附作者和联系方式 | oocore.core.view 或 oocore.admin |
均可，需相应权限 | /oo core about |
/oo core info |
无额外参数；用途与 about 相同 |
显示诊断，并附作者和联系方式 | oocore.core.view 或 oocore.admin |
均可，需相应权限 | oo core info |
/oo <节点> [参数…] 是已安装插件的路由语法，不是 Core 自带的业务命令。<节点> 必须由相应插件实际注册；省略 [参数…] 时向它传递空参数，其默认行为、权限和玩家/控制台限制由该插件决定。具体可运行示例请查对应产品页，Core 不代为承诺其命令已可用。
没有单字母 Core 缩写，也没有 Core 自带的 reload、清库或一键优化操作。注意：当前解析器对未知 Core 子命令或多余参数会退回显示诊断或忽略多余参数，出现输出不代表执行了该操作。例如输入 /oo core reload 不会重载配置；修改配置必须完整重启服务器。
权限¶
| 精确权限节点 | 对应功能 | 默认 OP | 默认普通玩家 | 实际继承 / 授权关系 |
|---|---|---|---|---|
oocore.core.view |
查看 Core 详情及 about / info 输出；允许在未知模块提示中查看已加载模块清单 |
有 | 无 | 没有声明子权限；单独授予不会获得 admin 权限 |
oocore.admin |
使用 core admin；也可查看其他 Core 详情 |
有 | 无 | 代码将其作为 Core 查看权限的替代授权；不是通过 descriptor 的 children 继承 |
oocore.command |
保留的 descriptor 权限声明；1.7.3 的根命令和 Core dispatcher 没有使用它作为访问门禁 | 有 | 有 | 无继承；拒绝该节点并不能阻止 /oo，授予它也不能解锁 Core 详情 |
这些是插件声明的默认值，服务器权限系统可以显式授予或拒绝相应节点。控制台没有额外的 Core 专用限制，详情调用同样通过发送者权限检查。仅授予 oocore.core.view 时，/oo core admin 仍会拒绝。
OOCore 未声明 oocore.* 通配权限，也未声明父子权限树；不要把权限管理插件自己的通配行为写成 OOCore 的内置功能。业务插件的权限独立管理，不要为了开放聊天等业务命令而向所有玩家授予 Core 管理权限。
变量与占位符¶
当前版本暂无对外变量/占位符。 以下类别均没有由 OOCore 1.7.3 提供的服主可用变量，不能把诊断字段当作替换语法。
| 类别 | 可用精确写法 | 含义 / 返回或显示示例 | 作用域 / 可用位置 | 必要前置与当前状态 |
|---|---|---|---|---|
| PlaceholderAPI（PAPI） | 无 | 不适用；Core 不提供 PAPI 变量值 | 没有 OOCore 自带的 PAPI expansion | 不需要安装 PAPI 来运行 Core；仅安装 PAPI 也不会新增 Core 占位符 |
| 消息模板变量 | 无 | Core 命令输出为程序生成，不提供服主模板替换值 | 没有 Core 消息模板配置文件 | 当前未提供 |
| UI 绑定变量 | 无 | 没有可直接填入 UI 的 Core 变量表达式 | Core 不提供窗口或 UI 绑定解析器 | 其他插件的 UI 变量以其正式文档为准 |
| 配置替换变量 | 无 | legacy-storage.enabled 是布尔配置项，不是占位符 |
config.yml 读取实际布尔值，不作变量替换 |
使用 true / false，不要填写变量表达式 |
诊断里的 server=、modules=、services= 是输出标签，不是 PAPI、消息或 UI 占位符。只读 API 数据也不自动构成可供服主填写的变量。
插件接入¶
服主只需安装正式服务端 JAR，无需编译 API 或修改开发工程。插件开发者通过稳定接口声明所需能力，并让任务、服务和存储遵守模块生命周期。
Command V2 的权限查询只对应贡献预先声明的单个非空权限节点；空声明不能再查询其他权限，也没有前缀、子节点或通配授权。这不是通用权限查询接口，具体业务权限应按该插件的正式接入方案处理。
构建与发布¶
OOCore 为专有软件，源码和内部开发工具不公开分发。服主使用作者正式提供的服务端 JAR；GitHub Release 中的更新日志说明本版变化，开发快照不等同正式版本。
升级时停服备份整个 plugins/OOCore/，再替换 JAR。1.7.3 默认禁用旧存储入口是安全行为变化：依赖旧入口的插件需要迁移；临时兼容开关只用于明确接受风险的过渡。不要热重载内核。
本次更新不迁移托管数据格式。如确需回滚，停服后恢复上一正式 1.7.2 JAR并保留相同托管数据；只有数据本身需要恢复时才使用备份。回滚旧版同时意味着放弃本版安全默认值与修复，应仅用于短期恢复；禁止回滚到已撤回的 1.7.0。
验收重点¶
安装后请确认：
- 日志中 OOCore 和所需业务插件正常启用，没有 unsupported、缺能力或缺依赖错误。
- 管理员可运行
/oo core，普通玩家不能读取 Core 详情。 - 新式模块存储正常工作；若旧插件因默认关闭旧入口报错，优先更新该插件。
- 重启后服务器 UID 与托管数据保持一致，没有重复安装的 Core JAR。
已知问题： 同步写入预算、未归因长 tick 和兼容验证缺口见未实现功能。请按已验证部署范围安装，不把未来计划当作当前能力。
OOConsole 集成¶
OOCore 已提供只读健康与平台诊断能力，但不会自行启动 HTTP 服务、开放网页端口或提供编辑器。安装 Core 不会自动出现控制台页面。
可视化入口由独立的 OOConsole 提供，实际可用功能和安装要求以其当前正式版本文档为准。Core 的接口可用，不等于所有业务插件的可视化页面都已交付。