HyDB

HyDB

HyDB为Hytale插件提供专业的SQLite数据库API。功能包括异步操作、每个世界和全局数据库、架构迁移、事务以及管理员调试命令。简单的API——安装一次，所有插件都能受益。

早期插件

HyDB - 面向 Hytale 的专业 SQLite 数据库 API

📊 概述

HyDB 是一款为 Hytale 设计的专业基础插件，提供了一套全面的 SQLite 数据库 API，用于持久化数据存储。它允许其他插件轻松存储和检索数据，而无需自行管理数据库连接。

可以将其视为一个数据库服务层——只需安装一次 HyDB，所有其他插件都可以使用它来进行可靠、快速且线程安全的数据存储。

✨ 主要功能

🗄️ 数据库管理

  • SQLite + JDBC - 行业标准嵌入式数据库（无需外部服务器）
  • 按世界 & 全局数据库 - 全局存储数据跨所有世界，或按世界分别存储
  • 自动连接管理 - HyDB 处理所有数据库生命周期
  • 基于文件的存储 - 每个插件拥有独立的数据库文件，实现完全隔离

⚡ 性能与安全

  • 异步操作 - 使用 Java 25 虚拟线程的非阻塞数据库调用
  • 线程安全 - 多插件/线程并发安全访问
  • 连接池 - 高效的资源管理
  • WAL 模式 - 预写式日志提升性能

🔧 完整的 API

  • 完整 CRUD 操作 - 通过简单 API 实现创建、读取、更新、删除
  • Schema 迁移 - 自动版本控制和升级数据库模式
  • 事务支持 - 原子化执行多个操作
  • Blob 存储 - 存储二进制数据（图片、文件、序列化对象）
  • 查询构建器 - 流畅式 API 用于构建复杂 SQL 查询
  • 预编译语句 - 内置 SQL 注入防护

🎮 游戏内管理命令

  • /hydb list - 查看所有数据库及文件大小
  • /hydb info <db> - 显示数据库详细信息和统计
  • /hydb tables <db> - 列出所有表及行数
  • /hydb query <db> "SQL" - 执行 SELECT 查询用于调试
  • 只读查询确保数据安全

📦 安装

  1. 下载 HyDB-1.0.0.jar
  2. 放入服务器的 mods 文件夹
  3. 重启服务器
  4. 完成！其他插件现在可以使用 HyDB

要求：

  • Hytale 服务器（最新版本）
  • Java 25+

👨‍💻 插件开发者指南

快速开始

// 获取 API
HyDBAPI api = HyDBPlugin.getAPI();

// 获取或创建数据库
Database db = api.getGlobalDatabase("myplugin");

// 创建表
db.createTable("users",
    "id INTEGER PRIMARY KEY AUTOINCREMENT",
    "uuid TEXT NOT NULL UNIQUE",
    "username TEXT NOT NULL",
    "coins INTEGER DEFAULT 0"
);

// 插入数据（异步）
Map<String, Object> data = new HashMap<>();
data.put("uuid", player.getUniqueId().toString());
data.put("username", player.getName());
data.put("coins", 100);

db.insertAsync("users", data).thenAccept(rows -> {
    System.out.println("玩家数据已保存！");
});

// 查询数据（异步）
db.queryFirstAsync("SELECT * FROM users WHERE uuid = ?", playerUUID.toString())
    .thenAccept(user -> {
        if (user != null) {
            int coins = (int) user.get("coins");
            // 使用数据
        }
    });

数据库作用域

// 全局数据库 - 跨所有世界共享（经济、玩家统计）
Database global = api.getGlobalDatabase("economy");

// 按世界数据库 - 按世界隔离（领地、区域）
Database world = api.getWorldDatabase(world, "claims");

🎯 适用场景

适用于需要以下功能的插件：

  • ✅ 经济系统 - 玩家余额、商店、交易
  • ✅ 玩家统计 - 数据跟踪、排行榜、成就
  • ✅ 领地系统 - 领地所有权、权限
  • ✅ 自定义游戏模式 - 游戏状态、进度跟踪
  • ✅ 社交功能 - 好友列表、公会、队伍
  • ✅ 管理工具 - 封禁、警告、操作日志
  • ✅ RPG 系统 - 角色数据、技能、背包
  • ✅ 任何持久化数据 - 所有需要重启后仍保留的数据

🏗️ 架构

数据库结构

HyDB/
├── global/              # 全局数据库
│   ├── economy.db       # 经济插件
│   ├── stats.db         # 统计插件
│   └── yourplugin.db    # 你的插件
└── worlds/              # 按世界数据库
    ├── world1/
    │   └── claims.db
    └── world2/
        └── claims.db

每个插件拥有独立的数据库文件，包含多个表，提供：

  • 完全的数据隔离
  • 简单的备份/恢复
  • 独立扩展
  • 无表名冲突

📖 文档

包含的文件：

  • README.md - 完整的 API 文档及示例
  • COMMANDS.md - 管理员命令参考
  • QUICK_START.md - 快速参考指南
  • EXAMPLE_USAGE.java - 完整可工作的示例插件
  • DATABASE_STRUCTURE.md - 架构细节

🔒 安全特性

  • 只读管理命令 - 查询命令仅允许 SELECT/PRAGMA
  • SQL 注入防护 - 全程使用预编译语句
  • 自动回滚 - 事务失败自动回滚
  • 错误处理 - 全面的错误信息和日志记录

🛠️ 技术细节

  • 语言: Java 25，使用现代特性（虚拟线程、switch 表达式）
  • 数据库: SQLite 3.47.1.0 + JDBC
  • 构建: 简单的 bash 构建脚本（无复杂构建工具）
  • 依赖: 已打包（SQLite JDBC、SLF4J）
  • 体积: ~14MB（包含所有依赖）

🌟 为什么选择 HyDB？

对于服务器所有者

✅ 一次安装，所有插件受益 ✅ 集中式数据库管理 ✅ 游戏内调试命令 ✅ 更好的服务器性能（共享连接池）

对于插件开发者

✅ 无需数据库管理代码 ✅ 简单直观的 API ✅ 异步操作防止卡顿 ✅ 文档详尽并附带示例 ✅ Schema 迁移支持

📊 对比

特性 HyDB JSON 文件 自定义数据库代码
易用性 ✅ 简单 API ✅ 非常简单 ❌ 复杂
性能 ✅ 快 ❌ 慢 ✅ 快
查询 ✅ SQL ❌ 有限 ✅ SQL
线程安全 ✅ 是 ❌ 否 ⚠️ 依赖实现
异步 ✅ 内置 ❌ 手动 ⚠️ 手动
迁移 ✅ 内置 ❌ 手动 ⚠️ 手动
事务 ✅ 内置 ❌ 否 ✅ 是

🚀 使用 HyDB 的示例插件

下载中包含完整的示例插件，展示了以下内容：

  • 带迁移的数据库设置
  • 玩家数据管理
  • 基于事务的操作
  • 查询构建器使用
  • 最佳实践

📝 许可证

开源 - 可免费用于 Hytale 服务器和插件开发。

🤝 支持与贡献

  • 问题反馈: 报告 bug 或请求功能
  • 文档: 包含全面的指南
  • 示例: 提供可工作的代码示例

🎉 立即开始使用！

  1. 在服务器上安装 HyDB
  2. 其他插件可立即使用该 API
  3. 使用 /hydb 命令进行调试和监控
  4. 享受可靠、快速的数据库存储！

版本: 1.0.0 兼容性: Hytale（当前版本） 模组作者: Oceride

让数据持久化变得简单而强大，适用于 Hytale 插件！ 这是一个必需的依赖/后端数据库模组。

图片由 GPT-4 生成