Inventory Manager API

InventoryManagerAPI

一款用于 Hytale 服务器的插件，提供强大的 API 来管理玩家物品栏，具备持久化保存/加载功能。

现已支持 PostgreSQL！

目的

InventoryManagerAPI 解决了 Hytale 服务器中物品栏持久化的常见问题。无论你是要构建需要保存/恢复玩家物品栏的小游戏、创建具有预设物品栏的自定义游戏模式，还是开发需要临时存储物品栏的插件，该 API 都能提供清晰、模块化的解决方案。

功能

• 保存玩家物品栏到持久化存储（JSON 文件）
• 按需恢复物品栏，完整保留所有物品数据
• 多种存储模式，适用于不同场景：
  • 基于 UUID - 简单的玩家专属存储
  • UUID + 后缀 - 每个玩家可拥有多个命名变体（例如 kit_pvp、kit_builder）
  • 自定义名称 - 共享/全局物品栏预设，任何玩家均可访问

特性

面向服务器管理员

• 内置指令用于手动管理物品栏
• 可配置行为（保存时清空物品栏、加载时删除物品栏文件）
• 持久的配置文件，支持游戏内修改

面向插件开发者

• 通过 InventoryManagerAPIPlugin.get().getInventoryStorageManager() 访问简洁 API
• 使用 CompletableFuture 实现异步操作，避免阻塞 I/O
• 策略模式支持自定义存储后端
• 完整物品栏支持：快捷栏、存储栏、背包、护甲栏和工具栏

---

指令

指令	描述
/invm save	保存当前物品栏
/invm load	恢复已保存的物品栏
/invm list	列出可用的已保存物品栏
/invm config view	查看当前配置
/invm config set <key> <value>	修改配置
/invm config save	保存配置到磁盘
/invm config reload	从磁盘重新加载配置

指令选项

保存/加载选项：

• --suffix <name> - 使用玩家专属的命名变体
• --name <name> - 使用共享/全局物品栏名称
• --clear true|false - 覆盖保存时清空设置
• --delete true|false - 覆盖加载时删除设置
• --player <name> - 对其他玩家执行操作

列表选项：

• --name - 显示自定义命名的物品栏
• --suffix - 显示基于后缀的物品栏
• --uuid <player> - 按指定玩家过滤

---

配置

配置文件位于 mods/DjCtavia.InventoryManagerAPI/InventoryManagerAPI.json。

常规设置

设置项	默认值	描述
StorageDirectory	mods/.../inventories	物品栏文件存储位置（仅 JSON 存储）
ClearInventoryOnSave	true	保存后清空玩家物品栏
DeleteFileOnLoad	true	恢复后删除物品栏文件
StorageType	Json	使用的存储后端（Json 或 PostgreSQL）

PostgreSQL 设置

以下设置仅在 StorageType 设置为 PostgreSQL 时使用。

设置项	默认值	描述
Host	localhost	PostgreSQL 服务器主机名
Port	5432	PostgreSQL 服务器端口
Database	postgres	数据库名称
Username	postgres	数据库用户名
Password	（空）	数据库密码
TableName	inventories	存储物品栏的表名

配置示例

JSON 存储（默认）

{
    "StorageDirectory": "mods/DjCtavia.InventoryManagerAPI/inventories",
    "ClearInventoryOnSave": true,
    "DeleteFileOnLoad": true,
    "StorageType": "Json",
    "PostgreSQL": {
        "Host": "localhost",
        "Port": 5432,
        "Database": "postgres",
        "Username": "postgres",
        "Password": "",
        "TableName": "inventories"
    }
}

PostgreSQL 存储

{
    "StorageDirectory": "mods/DjCtavia.InventoryManagerAPI/inventories",
    "ClearInventoryOnSave": true,
    "DeleteFileOnLoad": true,
    "StorageType": "PostgreSQL",
    "PostgreSQL": {
        "Host": "localhost",
        "Port": 5432,
        "Database": "hytale_server",
        "Username": "postgres",
        "Password": "your_password",
        "TableName": "inventories"
    }
}

---

API 使用示例

// 获取管理器
InventoryStorageManager manager = InventoryManagerAPIPlugin.get().getInventoryStorageManager();

// 按 UUID 保存物品栏
manager.saveInventory(playerUUID, inventory);

// 使用后缀保存（例如用于不同游戏模式）
manager.saveInventoryWithSuffix(playerUUID, inventory, "arena");

// 保存为命名预设（跨玩家共享）
manager.saveInventoryByName("starter_kit", inventory);

// 恢复物品栏
manager.restoreInventory(playerRef, store);

// 按后缀恢复
manager.restoreInventory(playerRef, store, "arena", null);

// 从命名预设恢复
manager.restoreInventoryByName(playerRef, store, "starter_kit", null);

// 列出可用物品栏
List<String> namedInventories = manager.listNamedInventories();
List<String> playerInventories = manager.listSuffixInventories(playerUUID);