- 版权类型
- 原创
- 插件中文名称
- skript-orm
- 插件英文名称
- skript-orm
- 支持的核心（服务端）
- Paper
- 语言支持
- English
- 前置组件
- Skript https://github.com/SkriptLang/Skript/
SkBee(Optional) https://github.com/ShaneBeee/SkBee
- 适配版本（Java）
- 最新版本
- 26.x
用 Skript 保存你的 Minecraft 服务器数据。 定义好表，就能用熟悉的 Skript 语法保存玩家档案、奖励记录和日志，开始使用不需要先学 SQL。
快速上手 · 完整示例 · 性能测试 · 源代码
为什么使用 skript-orm？
- 用 Skript 语法存数据。 插入、查询、更新、删除都有对应写法，查询结果直接存进普通 Skript 变量。
- 直接保存 Minecraft 数据。 UUID、物品、位置、日期和时间段都有对应的列类型。安装 SkBee 后还可以保存 NBT 复合标签。
- 统一检查输入。 结构化语句通过参数传值，并检查字段名和数据类型。玩家输入的名字或消息作为数据处理。自行执行原始语句时，也应正确传递输入值。
- 适合批量保存。 插件跨 tick 分段读取列表变量，再把数据库工作交给后台线程。MySQL 使用带参数的多行插入语句。
- 保存成功再继续。 当前触发器会等操作完成后继续执行，等待期间服务端仍能运行 tick。脚本可以检查操作结果，再告知玩家是否保存成功。
- 按服务器需要选择数据库。 MySQL、MariaDB、PostgreSQL、SQLite 和 MongoDB 都有真实数据库及 Paper 测试。具名连接让同一脚本可以使用多个数据库。
安装
使用 Paper 26.2、Skript 2.16.2、Java 25 或兼容的更新环境。SkBee 为可选依赖，只有 NBT 复合标签列需要。- 下载本站附件中的插件 jar。
- 将 jar 和 Skript 一起放入
plugins/，重启服务端。 - 在 Skript 的脚本目录中添加脚本，填写数据库连接信息，再加载脚本。
创建连接时填写什么类型？
MySQL、MariaDB、PostgreSQL、MongoDB 使用与数据库同名的连接类型，需要准备数据库服务和账号。SQLite 使用
"JDBC" 类型，在服务端保存数据库文件，不需要单独运行数据库服务。MySQL 和 SQLite 驱动由 Paper 提供，其他三个数据库的驱动由 Paper 在首次启动时下载。本插件尚未开放 MongoDB 事务。驱动下载方式和各数据库的操作限制，见 兼容性说明。
连接示例
请将占位符替换为你自己的数据库连接信息。
代码：
on load:
create a connection to database "MySQL" with properties:
url: "<你的数据库连接串>"
username: "<用户名>"
password: "<密码>"连接后，在脚本中声明表的列、类型和主键，就能开始保存和查询数据。注册表会创建缺失的表，但不会修改已有表的列。完整的玩家档案脚本见 玩家档案示例，其他常见用法见 完整示例。
真实服务端上的性能
随附测试图展示五种数据库完成相同批量读写任务的表现。在图中这次测试里，所有数据库的写入都在不到一秒内完成，读取约需十分之一秒。具体数据量、耗时和测试条件均列在图中。总耗时表示脚本等待操作完成的时间；最大 tick 间隔表示观察到的服务端 tick 延迟。把两者放在一起，是为了区分“脚本等了多久”和“服务器运行是否受到影响”。例如，图中的 MySQL 批量写入持续了多个 tick，但最大的 tick 间隔仍接近正常水平。
数据库操作在后台执行，大列表的输入分散到多个 tick 读取。保存查询结果、转换单个值等工作仍会用到主线程，因此依然可能出现 tick 延迟。共享测试主机和不同 CPU 会影响耗时，不能按这一次结果给数据库做普遍排名。
测试来源见 本次测试记录。其他数据量、重复运行、原始语句对照和测量限制，见 基准与压力测试。
使用时的限制：单次读取有行数上限，超出时拒绝整个结果，不会只保存一部分；较大的数据集请使用 分页查询。大批量写入会按绑定值和数据包限制拆成多条语句。批量保存完成前，请保持源变量不变。如果一组写入需要一起成功或撤销，请使用 事务。
与 skript-db 有什么区别？
skript-db 有多个同名项目。btk5h 原版和 Limework 分支主要让脚本执行 SQL 查询。skript-orm 则先声明列，再用结构化 Skript 语法完成常见读写，内置 Minecraft 类型和结果变量处理，减少自行维护的查询拼接与类型转换代码。上述 JDBC 插件处理 SQL 数据库，skript-orm 还提供 MongoDB 的结构化操作。原版和 Limework 项目也提供安全传值的接口。skript-orm 的结构化语句除了通过参数传值，还会检查声明的字段和数据类型；自行编写原始查询时，仍须正确处理输入。4w3 分支仍在维护，也支持参数绑定、批量操作和事务。安装前应确认具体分支和环境要求，不能把所有同名项目都视为已经停更。
skript-orm 提供跨 tick 读取批量输入和 MySQL 多行插入；skript-db 的批量执行方式取决于分支、查询写法和驱动。我们尚未与这些插件在同一服务端进行性能对照，图中的数据不能证明比它们快多少。希望沿用写 Skript 的方式存数据、保存 Minecraft 对象或导入列表时，skript-orm 能减少要自己处理的细节；依赖复杂联表或数据库专属查询的脚本，也可以选择直接使用 SQL 的插件。
文档与反馈
快速上手 · 写入行 · 读取行 · 类型 · 错误与等待 · 故障排查项目按 MIT 许可开源。反馈问题时，请附上服务端、Skript 和数据库版本，以及出错脚本和相关日志。
