持久化状态存储

项目的大多数世界存档记录通过内部工具 IsekaiPersistData 保存到 data/isekaiexpansion/ 下的版本化文件。作用域由所选持久化状态管理器决定；文件名带版本号并不意味着旧数据会自动迁移。

它做什么

internal.persiststate.IsekaiPersistData 继承 Minecraft 的 PersistentState，创建父目录，再将加载与缓存交给 PersistentStateManager.getOrCreate。它是内部存储约定，不是公共 API 门面，也不协调跨记录事务。

服务器重载始终使用主世界管理器；管理器重载则使用传入的具体管理器。因此，从下界访问服务器级记录仍会落到主世界数据中，而世界级城市或住房记录保存在对应世界的数据目录。

运行时模型

当前文件清单

以下路径相对于所选管理器的数据目录。记录按需加载，列出路径不代表对应文件已经存在。

阵营和演出状态也提供管理器重载，直接调用时可选择其他作用域。表中的服务器作用域描述正常运行时调用方。任务分片使用服务器任务状态传入的管理器，不随玩家当前维度变化。

伙伴名额账本

通过 api.taming.TamedCompanionsAPI 的 limit(player) 和 occupied(player) 查询上限与已用名额，也可预留或释放所有权记录。所有权变更须在服务器线程执行；reserve(entity, owner) 返回拒绝时，调用方必须取消所有权赋值。该接口支持 TameableEntity 与 AbstractHorseEntity 及其子类。

internal.taming.TamedCompanionLedger 通过主世界的共享存储记录保存数据，维护实体 UUID → 主人 UUID 与主人 UUID → 已占用实体两个索引。TamedCompanionsComponent 只向所属玩家同步计数，不负责判定剩余名额。服务器线程在所有权改变前检查并预留名额；重复设置同一所有权不会多占名额。

死亡会移除存活名额，并将带名字的通知加入待处理记录。主人在线时立即刷新组件并发送通知；主人离线时，队列随存档保留。登录后从账本刷新组件、发送通知，再清除该主人的死亡记录。存活实体的区块卸载或跨维度移动不会释放名额；显式丢弃实体或解除所有权才会释放。从存档加载的死亡实体不会重新占用存活名额。

世界树例外

world.terrain.placement.WorldTreeState 直接继承 PersistentState，在管理器数据根目录使用 isekaiexpansion_world_tree.dat，没有走共享工具的版本化路径。其内容具有独立的版本与几何验证。

接入时会恢复有效预留位置，或选定并记录新位置，然后显式保存管理器。解码后的预留数据无效会中止接入，不会悄悄重新选址。不要把此文件移动到共享工具目录，也不要认为所有项目持久化状态都遵循该工具。

约定

相关世界存在后，在服务器线程修改状态。持久数据发生变化时标记为脏；修改 getter 返回的对象不会自动通知此工具。区分实体组件、客户端缓存和服务器持久记录，游戏逻辑应调用所属服务，而非直接修改运行中的 NBT。

扩展方式

项目内部状态可以采用以下模式。示例保存计数器，仅在修改时标记为脏：

final class ExampleState extends IsekaiPersistData {
    private static final Key KEY = key("example", "counter", 1);
    private int count;

    static ExampleState get(MinecraftServer server) {
        return IsekaiPersistData.get(server, KEY, ExampleState::read, ExampleState::new);
    }
    private static ExampleState read(NbtCompound nbt) {
        var state = new ExampleState();
        state.count = nbt.getInt("Count");
        return state;
    }
    void increment() { count++; markDirty(); }
    @Override public NbtCompound writeNbt(NbtCompound nbt) {
        nbt.putInt("Count", count);
        return nbt;
    }
}

选择键之前先确定服务器级或世界级作用域。兼容格式保持键不变，并明确读取器对缺失/无效字段的处理。所属系统自行增加的缓存也必须遵循服务器或世界生命周期。

验证

• 从不同维度加载并修改服务器级状态，确认解析到同一主世界记录。
• 在不同世界修改同一世界级键，重启后确认记录相互独立。
• 测试无效域/名称/版本及不可用存储目录，区分目录错误日志与持久化成功。
• 对所属 NBT 格式进行往返测试，涵盖缺失和无效字段。在一次性存档中测试版本变化，确认迁移或新建状态策略符合预期。
• 对已保存的世界树预留位置分别测试恢复和无效几何；接入过程不得静默搬移地标。

相关页面

• 地形生成——完整世界树载荷与绑定失败规则。
• 地下城运行时——聚合 NBT、分配校验与重启恢复。
• NPC 复活：墓地快照与支付约定。
• 城市 API：世界级城市记录。
• 声望运行时：阵营存储与覆盖。
• 蓝图研究：委托存储与事务。
• 人形运行时：绘制数据和配置归属。