数据同步库

DataSyncLib

面向 Minecraft 模组开发的注解驱动自动数据同步与持久化框架。

---

📖 概述

DataSyncLib 是一个为 Minecraft 模组开发者设计的功能强大的数据同步库。它通过使用声明式 Java 注解，消除了手动处理网络数据包和 NBT 持久化的繁琐样板代码。

只需使用 @SyncToClient、@SyncToServer 或 @SaveToDisk 注解你的字段，DataSyncLib 便会自动处理：

• 🔁 客户端-服务器字段同步 — 异步安全，增量差异同步
• 💾 磁盘持久化 — 带变更检测的自动 NBT 保存/加载
• 📡 网络传输 — 基于索引寻址的协议，仅发送已变更的字段
• 🔧 自定义编解码器 — 30+ 预注册类型，可通过 @Codec 扩展

---

✨ 核心特性

特性	描述
🔁 双向同步	@SyncToClient 和 @SyncToServer 处理服务器与客户端之间的字段同步。完全异步安全。
💾 自动持久化	带有 @SaveToDisk 注解的字段会被自动写入和读取自 NBT。
📡 增量同步	内置脏标记检测 — 仅通过网络传输已变更的字段。
🔧 可扩展编解码器系统	带有 30+ 预注册类型的 DataSyncCodec 注册表。可通过 @Codec 注册自定义编解码器。
📢 变更通知	字段级监听器回调 + 用于响应式 UI 更新的 NotifiableHolder 系统。
📦 数据组件系统	基于标识键的组件数据模型，包含 DataComponentRegistry 和 DataComponentMap。
🗂️ 注册表工具	带有冻结/解冻生命周期和内置序列化的通用注册表。
⚡ 高性能	使用 MethodHandle 而非反射，FastUtil 集合，多级缓存，VarInt 编码。
🗜️ 紧凑数据格式	自定义的 19 类型二进制数据系统，比 NBT Tag 更紧凑。
🧩 开箱即用	继承 FieldDataHolderBlockEntity — 立即可获得全部功能。
🪆 嵌套持有器	@AdditionalHolder 在嵌套对象中递归地发现带注解的字段。
🎯 自定义策略	@Strategy 用于对复杂类型（如 ItemStack、FluidStack 等）进行自定义哈希/相等性变更检测。

---

🚀 快速入门

public class MyBlockEntity extends FieldDataHolderBlockEntity {
@SyncToClient
@SaveToDisk
private int energy = 0;

@SyncToClient(notifyUpdate = true)  // 在客户端触发 scheduleUpdate
private String status = "idle";

@SyncToServer(autoUpdate = false)   // 仅在显式标记时同步
private int clientConfig = 0;

public MyBlockEntity(BlockPos pos, BlockState state) {
    super(ModBlockEntities.MY_BLOCK_ENTITY.get(), pos, state);
}

public void serverTick(ServerLevel level) {
    energy++;
    setChanged();  // 标记区块为需要保存
    DataSyncNetwork.syncBlockEntityToClient(this, false, true);  // 异步安全
}

@Override
public void scheduleUpdate(LogicalSide side) {
    if (side.isClient()) {
        // 在客户端重新渲染或刷新 UI
    }
}

}

嵌套持有器

public class MachineBlockEntity extends FieldDataHolderBlockEntity {
@AdditionalHolder  // 扫描 InventoryData 中带注解的字段
private InventoryData inventory = new InventoryData();

@AdditionalHolder
private EnergyData energy = new EnergyData();

}
class InventoryData {
    @SaveToDisk @SyncToClient
    private int itemCount;
}
class EnergyData {
    @SaveToDisk @SyncToClient(condition = "shouldSyncEnergy")
    private long storedEnergy;
private boolean shouldSyncEnergy(long value) {
    return value > 0;  // 当能量为空时跳过同步
}

}

自定义编解码器

// 1. 定义编解码器 — FieldDataManager 会自动发现 POJO 上带 @SaveToDisk 注解的字段
private static final FieldDataCodec<MyConfig> CONFIG_CODEC =
    FieldDataManager.createCodec(MyConfig.class, MyConfig::new);
// 2. 在字段上引用
@SaveToDisk @SyncToClient
@Codec(saveCodec = "CONFIG_CODEC", syncCodec = "CONFIG_CODEC")
private MyConfig config = new MyConfig();

实体同步

public class MyEntity extends Entity implements IFieldDataHolder {
private final LazyFieldDataManager fieldDataManager = new LazyFieldDataManager(this);

@SyncToClient
private int state = 0;

@Override
public FieldDataManager getFieldDataManager() {
    return fieldDataManager.get();
}

@Override
public void tick() {
    if (!level().isClientSide()) {
        state = calculateState();
        DataSyncNetwork.syncEntityToClient(this);
    }
}

}

---

📋 注解参考

注解	用途	关键属性
@SyncToClient	服务器 → 客户端同步	autoUpdate、notifyUpdate、condition、listener
@SyncToServer	客户端 → 服务器同步	autoUpdate、notifyUpdate、condition、listener
@SaveToDisk	磁盘持久化	key、condition、saveNull、defaultValue、defaultValueGetter
@Access	强制容器的访问模式	createInstance
@AdditionalHolder	递归扫描嵌套对象字段	—
@Codec	自定义序列化	saveCodec / syncCodec / writeToData / readFromData
@Strategy	自定义变更检测策略	value（静态字段名）
@Generic	强制使用泛型类型的工厂解析	—
@AddToManager	添加到管理器但不进行自动同步/持久化	—

---

📦 安装

前置要求

• Java 21

对于开发者

repositories {
    maven {
        url = "https://maven.gtodyssey.com/releases"
    }
}
dependencies {
    implementation fg.deobf("com.gto:datasynclib-forge-1.20.1:26.7.4")
}

---

📖 完整文档

包含架构图、数据流图、API 参考及高级用法指南的详细文档：

• 英文文档 — 在浏览器中打开以获得最佳体验
• 中文文档 — 中文完整文档

---

🏗️ 架构

Annotations → FieldDefinitionStorage → DataFieldDefinition[]
                                            ↓
IFieldDataHolder → LazyFieldDataManager → FieldDataManager → DataField[]
                    (DCL 懒加载)            (实例级)        (AbstractField / AbstractFieldAccess)

组件	职责
FieldDefinitionStorage	全局缓存 — 扫描类层次结构以查找带注解的字段
FieldDataManager	实例级生命周期管理器 — 字段发现、变更检测、序列化
DataField 层次结构	AbstractField（原始值）、ObjField（带编解码器的对象）、AbstractFieldAccess（集合/映射/数组）
DataSyncCodec	统一编解码器注册表，将 ByteStreamCodec（网络）与 DataCodec（持久化）配对
Data 类型系统	19 类型密封二进制格式，比 NBT 更紧凑，支持 VarInt 编码

---

💡 灵感来源

本项目灵感来源于 LDLib 的 syncdata 包，由 Low-Drag-MC 开发，这是一个适用于 Minecraft 模组开发的功能强大的多加载器库。

---

📄 许可证

本项目采用 GNU LGPL 3.0 许可证 — 你可以自由地在自己的模组中使用、修改和分发此库。