同步处理器（value/sync 包）

基本信息

属性 值
包路径 com.cleanroommc.modularui.value.sync
文件数 36
抽象根 SyncHandler<S>（value/sync/SyncHandler.java:32，abstract，implements ISyncOrValue）
工厂 SyncHandlers（value/sync/SyncHandlers.java）
承载封包 PacketSyncHandler（network/packets/PacketSyncHandler.java）

功能

类层次

SyncHandler<S> (value/sync/SyncHandler.java:32)  abstract, implements ISyncOrValue
├── ValueSyncHandler<T,S> (ValueSyncHandler.java:9)  abstract, implements IValueSyncHandler<T>
│   ├── BooleanSyncValue (BooleanSyncValue.java:17) / ByteSyncValue (ByteSyncValue.java:15)
│   ├── ShortSyncValue (ShortSyncValue.java:17) / IntSyncValue (IntSyncValue.java:18)
│   ├── LongSyncValue (LongSyncValue.java:18) / FloatSyncValue (FloatSyncValue.java:18)
│   ├── DoubleSyncValue (DoubleSyncValue.java:18) / StringSyncValue (StringSyncValue.java)
│   ├── EnumSyncValue<T,S> (EnumSyncValue.java:17) / BinaryEnumSyncValue
│   ├── BigDecimalSyncValue / BigIntSyncValue
│   ├── LongArraySyncValue / ByteArraySyncValue
│   ├── FluidSlotSyncHandler (FluidSlotSyncHandler.java:21)   值类型为 FluidStack
│   ├── AbstractGenericSyncValue<T,S> (AbstractGenericSyncValue.java:16)  abstract
│   │   └── GenericSyncValue<T,S> (GenericSyncValue.java:48)
│   └── GenericCollectionSyncHandler<T,C,S> (GenericCollectionSyncHandler.java:20)  abstract
│       ├── GenericListSyncHandler<T> (GenericListSyncHandler.java:22)  值类型 List<T>
│       ├── GenericSetSyncHandler<T> (GenericSetSyncHandler.java:19)   值类型 Set<T>
│       └── GenericMapSyncHandler<K,V> (GenericMapSyncHandler.java:20) 值类型 Map<K,V>
├── DynamicSyncHandler (DynamicSyncHandler.java:25)      implements IDynamicSyncNotifiable
├── DynamicLinkedSyncHandler<S> (DynamicLinkedSyncHandler.java:22)  implements IDynamicSyncNotifiable
├── ItemSlotSH (ItemSlotSH.java:19)
├── PhantomItemSlotSH (PhantomItemSlotSH.java)
├── CursorSlotSyncHandler (CursorSlotSyncHandler.java:9)
├── InteractionSyncHandler (InteractionSyncHandler.java:12)
└── PanelSyncHandler (PanelSyncHandler.java:22)  final, implements IPanelHandler

管理器类（不继承 SyncHandler）：

类 文件 作用
ModularSyncManager value/sync/ModularSyncManager.java 界面级同步管理
PanelSyncManager value/sync/PanelSyncManager.java 面板级同步管理
ISyncRegistrar value/sync/ISyncRegistrar.java 同步键名生成（makeSyncKey(String,int)）
SyncedAction value/sync/SyncedAction.java 同步动作
IDynamicSyncNotifiable value/sync/IDynamicSyncNotifiable.java 动态同步通知

SyncHandlers：8 个静态工厂

SyncHandlers（value/sync/SyncHandlers.java）是给其他 mod 用的推荐入口， 提供 8 个静态方法：

方法 行 返回类型 说明
intNumber(IntSupplier, IntConsumer) :23 IntSyncValue 整型
longNumber(LongSupplier, LongConsumer) :27 LongSyncValue 长整型
bool(BooleanSupplier, BooleanConsumer) :31 BooleanSyncValue 布尔
doubleNumber(DoubleSupplier, DoubleConsumer) :35 DoubleSyncValue 双精度
string(Supplier<String>, Consumer<String>) :39 StringSyncValue 字符串
itemSlot(IItemHandlerModifiable, int index) :43 ModularSlot 物品槽位（直接返回槽位对象）
fluidSlot(IFluidTank) :47 FluidSlotSyncHandler 流体槽位
enumValue(Class<T>, Supplier<T>, Consumer<T>) :51 EnumSyncValue<T,?> 枚举
generic(Class<T>) :55 GenericSyncValue.Builder<T> 泛型值（返回构建器）

共 9 个方法（grep -c 'public static' 为 9），上表按语义列出前 8 个 + 泛型构建器。

itemSlot(...)（:43）返回的是 ModularSlot（widgets/slot/ModularSlot.java:30）—— 即一个真正的原版 Slot，可直接塞进 ModularContainer。

类型交叉：一个值可被多种同步方式处理

多个 *SyncValue 同时实现多个同步接口，使服务端可用不同粒度读写同一种值：

值类 实现的同步接口
BooleanSyncValue IBoolSyncValue, IStringSyncValue
IntSyncValue IIntSyncValue, IDoubleSyncValue, IStringSyncValue
LongSyncValue ILongSyncValue, IIntSyncValue, IStringSyncValue
ShortSyncValue IShortSyncValue, IIntSyncValue, IStringSyncValue
FloatSyncValue IFloatSyncValue, IDoubleSyncValue, IStringSyncValue
DoubleSyncValue IDoubleSyncValue, IFloatSyncValue, IStringSyncValue
EnumSyncValue IEnumValue, IIntSyncValue

（行号见上表各文件的 public class 声明，例如 IntSyncValue.java:18、 LongSyncValue.java:18、EnumSyncValue.java:17、FloatSyncValue.java:18。）

这套设计让同一个同步值既能按整型同步，也能降级按字符串或双精度同步， 从而在带宽与精度间取舍。

动态同步：客户端发请求、服务端裁决

DynamicSyncHandler（:25）与 DynamicLinkedSyncHandler（:22） 实现 IDynamicSyncNotifiable：客户端交互（如点击开关）不会直接改值， 而是把请求发给服务端；服务端执行 IServerMouseAction / IServerKeyboardAction （api/value/sync/ 下各 1 个接口）后再回写给所有客户端。

InteractionSyncHandler（:12）是这套机制的薄封装。

数值

数值名 值
同步处理器类总数 36（`ls value/sync/*.java
SyncHandlers 静态工厂数 9
同步管理器数 2（ModularSyncManager、PanelSyncManager）

交互

触发 行为
界面打开 Widget.initialiseSyncHandler(ModularSyncManager, boolean late)（widget/Widget.java:103）按 syncHandler(name,id) 绑定的键建立同步
服务端值变化 通过 PacketSyncHandler 广播给所有客户端
客户端交互 DynamicSyncHandler 把请求发到服务端，服务端裁决后回写
玩家登出 ModularNetwork.SERVER.onPlayerLeave(player) 清空该玩家状态（CommonProxy.java:78）

相关条目