数据模型

Workspace、Vault、Item、Quota、AutoPickup 等数据结构与示例

数据模型

本文档介绍 Zephyrion 的核心数据模型类。

导入

import com.faithl.zephyrion.core.models.*

Workspace (工作空间)

工作空间是物品存储的顶级容器。

属性

属性类型说明
idInt工作空间 ID
nameString工作空间名称
descString?描述
typeWorkspaceType类型
ownerString创建者 UUID
membersString成员列表(逗号分隔的 UUID)
createdAtLong创建时间戳
updatedAtLong更新时间戳

WorkspaceType 枚举

enum class WorkspaceType {
    PUBLIC,      // 公共工作空间 - 成员可访问
    PRIVATE,     // 私有工作空间 - 仅创建者可访问
    INDEPENDENT  // 独立工作空间 - 每人独立存储
}

实例方法

// 获取格式化的创建时间
fun getCreatedAt(): String

// 获取格式化的更新时间
fun getUpdatedAt(): String

// 获取创建者(OfflinePlayer)
fun getOwner(): OfflinePlayer

// 获取所有成员
fun getMembers(): List<OfflinePlayer>

// 获取成员名称列表
fun getMembersName(): List<String>

// 检查是否为成员
fun isMember(uuid: String): Boolean

// 重命名工作空间
fun rename(newName: String): ZephyrionAPI.Result

// 更新描述
fun updateDesc(newDesc: String?)

// 删除工作空间
fun delete()

示例

val workspace = ZephyrionAPI.getWorkspace(playerUUID, "MyWorkspace")
if (workspace != null) {
    println("名称: ${workspace.name}")
    println("类型: ${workspace.type}")
    println("创建者: ${workspace.getOwner().name}")
    println("成员: ${workspace.getMembersName().joinToString(", ")}")
    println("创建时间: ${workspace.getCreatedAt()}")
    
    // 检查玩家是否是成员
    if (workspace.isMember(player.uniqueId.toString())) {
        println("你是这个工作空间的成员")
    }
}

Vault (保险库)

保险库归属于工作空间,用于存储物品。

属性

属性类型说明
idInt保险库 ID
nameString保险库名称
descString?描述
workspaceIdInt所属工作空间 ID
sizeInt当前容量(槽位数)
createdAtLong创建时间戳
updatedAtLong更新时间戳

计算属性

// 获取所属工作空间
val workspace: Workspace

实例方法

// 获取格式化的创建时间
fun getCreatedAt(): String

// 获取格式化的更新时间
fun getUpdatedAt(): String

// 获取最大页数
fun getMaxPage(): Int

// 增加容量(消耗配额)
fun addSize(add: Int): Boolean

// 减少容量(返还配额)
fun removeSize(remove: Int): Boolean

// 重命名保险库
fun rename(newName: String): ZephyrionAPI.Result

// 更新描述
fun updateDesc(newDesc: String?)

// 删除保险库
fun delete(): Boolean

容量计算

每页 36 个槽位,最大页数计算:

val maxPage = ceil(size.toDouble() / 36).toInt()
// 至少为 1 页

示例

val vaults = ZephyrionAPI.getVaults(workspace)
vaults.forEach { vault ->
    println("保险库: ${vault.name}")
    println("容量: ${vault.size} 槽位 (${vault.getMaxPage()} 页)")
    println("工作空间: ${vault.workspace.name}")
    
    // 扩展容量
    if (vault.addSize(36)) {
        println("成功扩展 36 个槽位")
    }
}

Item (物品)

存储在保险库中的物品数据。

属性

属性类型说明
idInt物品记录 ID
vaultIdInt所属保险库 ID
pageInt页码
ownerString?所有者 UUID(独立工作空间用)
slotInt槽位 (0-35)
itemStackSerializedString序列化的物品数据(Base64)

计算属性

// 获取/设置 ItemStack
var itemStack: ItemStack

// 获取所属保险库
val vault: Vault

实例方法

// 获取物品名称
fun getName(): String

// 获取物品 Lore
fun getLore(): List<String>

ItemStack 序列化扩展

// 序列化为 Base64
fun ItemStack.toBase64(): String

// 从 Base64 反序列化
fun String.base64ToItemStack(): ItemStack

示例

// 获取物品列表
val items = ZephyrionAPI.getItems(vault, page = 1, player)
items.forEach { item ->
    println("槽位 ${item.slot}: ${item.getName()}")
    println("Lore: ${item.getLore().joinToString(", ")}")
    
    // 获取实际的 ItemStack
    val itemStack = item.itemStack
    println("类型: ${itemStack.type}, 数量: ${itemStack.amount}")
}

// 搜索物品
val diamonds = ZephyrionAPI.searchItemsByName(vault, "钻石")
diamonds.forEach { item ->
    println("找到钻石在 第${item.page}页 槽位${item.slot}")
}

Quota (配额)

玩家的配额数据。

属性

属性类型说明
idInt记录 ID
playerString玩家 UUID
workspaceQuotasInt工作空间配额上限
workspaceUsedInt已使用的工作空间数量
sizeQuotasInt存储配额上限
sizeUsedInt已使用的存储槽位
unlimitedBoolean是否无限容量

示例

val quota = ZephyrionAPI.getUserData(player.uniqueId.toString())

println("工作空间: ${quota.workspaceUsed}/${quota.workspaceQuotas}")
println("存储容量: ${quota.sizeUsed}/${quota.sizeQuotas}")
println("无限容量: ${if (quota.unlimited) "是" else "否"}")

// 检查是否可以创建工作空间
val canCreateWorkspace = quota.workspaceUsed < quota.workspaceQuotas

// 计算剩余存储空间
val remainingSize = if (quota.unlimited) Int.MAX_VALUE else quota.sizeQuotas - quota.sizeUsed

AutoPickup (自动拾取规则)

保险库的自动拾取配置。每个玩家有独立的规则配置。

属性

属性类型说明
idInt规则 ID
typeAutoPickupType规则类型
valueString规则值
vaultIdInt所属保险库 ID
ownerString规则所有者 UUID
createdAtLong创建时间戳
updatedAtLong更新时间戳

AutoPickupType 枚举

enum class AutoPickupType {
    ITEM_PICKUP,      // 拾取规则 - 匹配的物品自动存入
    ITEM_NOT_PICKUP   // 不拾取规则 - 匹配的物品不会拾取
}

计算属性

// 获取所属保险库
val vault: Vault

实例方法

// 删除规则
fun deleteRule(): Boolean

// 更新规则值
fun updateValue(newValue: String): ZephyrionAPI.Result

规则值格式

前缀格式说明
type:type:DIAMOND匹配材料类型
name:name:钻石剑匹配名称包含
lore:lore:稀有匹配 Lore 包含
regex:regex:.*钻石.*正则匹配名称
regex-lore:regex-lore:.*传说.*正则匹配 Lore
(无前缀)钻石默认匹配名称包含

示例

val owner = player.uniqueId.toString()

// 获取所有规则(需要指定 owner)
val rules = ZephyrionAPI.getAutoPickups(vault, owner)
rules.forEach { rule ->
    val typeStr = when (rule.type) {
        AutoPickupType.ITEM_PICKUP -> "拾取"
        AutoPickupType.ITEM_NOT_PICKUP -> "不拾取"
    }
    println("[$typeStr] ${rule.value}")
}

// 创建拾取钻石的规则
ZephyrionAPI.createAutoPickup(
    vault = vault,
    type = AutoPickupType.ITEM_PICKUP,
    value = "type:DIAMOND",
    owner = owner
)

// 创建不拾取圆石的规则
ZephyrionAPI.createAutoPickup(
    vault = vault,
    type = AutoPickupType.ITEM_NOT_PICKUP,
    value = "type:COBBLESTONE",
    owner = owner
)

// 检查物品是否应该拾取
val item = ItemStack(Material.DIAMOND, 1)
when (ZephyrionAPI.shouldAutoPickup(item, vault, owner)) {
    true -> println("物品将被自动拾取")
    false -> println("物品被排除")
    null -> println("无匹配规则")
}

Setting (设置)

保险库的设置数据。每个玩家有独立的设置配置。

属性

属性类型说明
idInt设置 ID
settingString设置键名
valueString设置值
vaultIdInt所属保险库 ID
ownerString设置所有者 UUID
createdAtLong创建时间戳
updatedAtLong更新时间戳

静态方法

// 获取设置值(使用缓存)
fun get(vault: Vault, setting: String, owner: String): String?

// 获取设置值,不存在则返回默认值
fun getOrDefault(vault: Vault, setting: String, owner: String, default: String): String

// 设置值(创建或更新)
fun set(vault: Vault, setting: String, value: String, owner: String)

// 创建设置
fun create(vault: Vault, setting: String, value: String, owner: String)

// 删除设置
fun delete(vault: Vault, setting: String, owner: String)

内置设置键

设置键类型说明
auto_replaceBoolean工具自动替换开关

示例

val owner = player.uniqueId.toString()

// 获取自动替换设置
val autoReplace = Setting.getOrDefault(vault, "auto_replace", owner, "false").toBoolean()

// 启用自动替换
Setting.set(vault, "auto_replace", "true", owner)

// 禁用自动替换
Setting.set(vault, "auto_replace", "false", owner)

关系图

Player
  └── Quota (1:1)
  └── Workspace (1:N, 通过 members)
        └── Vault (1:N)
              └── Item (1:N)
              └── AutoPickup (1:N)
              └── Setting (1:N)

数据库表结构

quotas 表

字段类型说明
idINT主键
playerVARCHAR玩家 UUID
workspace_quotasINT工作空间配额
workspace_usedINT已用工作空间数
size_quotasINT存储配额
size_usedINT已用存储数
unlimitedBOOLEAN无限容量标记

workspaces 表

字段类型说明
idINT主键
nameVARCHAR名称
descriptionTEXT描述
typeVARCHAR类型
ownerVARCHAR创建者 UUID
membersTEXT成员列表
created_atBIGINT创建时间
updated_atBIGINT更新时间

vaults 表

字段类型说明
idINT主键
nameVARCHAR名称
descriptionTEXT描述
workspace_idINT工作空间 ID
sizeINT容量
created_atBIGINT创建时间
updated_atBIGINT更新时间

items 表

字段类型说明
idINT主键
vault_idINT保险库 ID
pageINT页码
ownerVARCHAR所有者 UUID
slotINT槽位
item_stackTEXT序列化物品

auto_pickups 表

字段类型说明
idINT主键
typeVARCHAR规则类型
valueVARCHAR规则值
vault_idINT保险库 ID
ownerVARCHAR规则所有者 UUID
created_atBIGINT创建时间
updated_atBIGINT更新时间

settings 表

字段类型说明
idINT主键
settingVARCHAR设置键名
valueVARCHAR设置值
vault_idINT保险库 ID
ownerVARCHAR设置所有者 UUID
created_atBIGINT创建时间
updated_atBIGINT更新时间

On this page