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。

开发快照不是正式版本：当前开发树为 1.8.0-SNAPSHOT，尚不具备正式发布条件；没有新的 Release、安装包或正式 SDK 下载。新增平台能力仍需完成契约、平台与实服验证，离线测试和隔离构建不等于正式支持。
通道与平台能力仍受限：1.8 通道 I/O 生产入口保持关闭，仍待宿主部署批准与加载来源验证；新增 Folia 能力尚未验收，不能作为可用功能部署。
优先继续性能定位：使用可比较的负载检查内存分配、存活对象、GC 暂停与 MSPT 尾部尖峰，再决定后续优化；不先承诺节省比例或加速幅度。
改进存储扩展能力：有界异步存储已进入 Code-prepared / 测试中，尚未正式提供。已完成定向磁盘与生命周期测试，覆盖排队上限、内存预算、退出撤销，以及写入结果与持久性保障的区分；事务型迁移与恢复工具不因此视为已交付。定向测量仅表明等待磁盘的工作移出了调用线程，不证明 TPS、MSPT 或总内存改善。完整 Paper 异步负载、其他平台及真实业务联动仍待验收。
逐项扩大兼容验证：在对应上游构建可用时分别评估 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 的接口可用，不等于所有业务插件的可视化页面都已交付。