元数据追踪器

Metadatahandler 为每个实体提供一个 动态的键值对存储空间，允许开发者在运行时随意附加、读取或移除任意类型的自定义数据，而无需修改实体类本身。

核心价值在于 解耦数据与实体，让技能系统、事件追踪、状态管理等逻辑可以独立维护各自的临时数据，互不干扰。

键名约定

键名使用 String 类型，建议遵循以下命名习惯以提高可读性和避免冲突：

风格	示例	适用场景
蛇形命名	last_attack_time	通用状态记录
命名空间前缀	myplugin:stun_ticks	跨插件共享，防止键名冲突
布尔标志	immune_to_fire	开关类状态

接口方法

所有方法均提供 UUID 和 LivingEntity 两组重载，方便在不同上下文中使用。

设置元数据 — setMeta

// 记录玩家最后一次攻击时间
handler.setMeta(playerUUID, "last_attack_time", System.currentTimeMillis())

// 标记实体处于无敌状态
handler.setMeta(monster, "invincible", true)

检查元数据 — hasMeta

// 检查是否有无敌标记
if (handler.hasMeta(player, "invincible")) {
    cancelDamage()
}

// 检查技能是否在冷却中
if (handler.hasMeta(player, "cooldown_fireball")) {
    sendMessage("技能冷却中")
    return
}

获取元数据 — getMeta

// 获取上次攻击时间，不存在则返回 null
def lastAttack = handler.getMeta(playerUUID, "last_attack_time") as Long?

// 获取无敌状态，带默认值
def isInvincible = handler.getMeta(player, "invincible") as Boolean ?: false

// 获取自定义对象（需手动转型）
def stats = handler.getMeta(player, "combat_stats") as Map?
if (stats != null) {
    println "击杀数: ${stats.kills}"
}

移除元数据 — removeMeta

// 无敌状态结束，移除标记
handler.removeMeta(player, "invincible")

// 技能冷却结束
handler.removeMeta(player, "cooldown_fireball")