Nuclear Control API
基本信息
| 属性 | 值 |
|---|---|
| 包名 | shedar.mods.ic2.nuclearcontrol.api |
| Forge API 标记 | @API(owner = "IC2NuclearControl", apiVersion = "v1.0.5", provides = "NuclearControlAPI")（api/package-info.java:1） |
| 源码文件数 | 16（ls api/*.java | wc -l = 16） |
| 分发限制 | 包注释明确声明「请勿分发本包」（package-info.java:2-4） |
本 API 用于让其他模组编写自定义卡片，插入本模组的信息屏渲染数据，或让自定义方块被温度监控器 / 范围触发器识别为可读目标。
接口
| 接口 | 作用 | 引用 |
|---|---|---|
IPanelDataSource |
卡片主契约，实现它即可在信息屏上显示数据 | api/IPanelDataSource.java:16 |
ICardWrapper |
卡片数据读写包装器（NBT 键值对） | api/ICardWrapper.java:8 |
IRemoteSensor |
标记接口：声明卡片只有一个目标方块 | api/IRemoteSensor.java:10 |
IRangeTriggerable |
标记接口：声明卡片可被范围触发器使用 | api/IRangeTriggerable.java:9 |
IPanelMultiCard |
多变体卡片（一张卡按状态返回不同设置与类型） | api/IPanelMultiCard.java:6 |
IAdvancedCardSettings |
卡片提供「高级设置」界面 | api/IAdvancedCardSettings.java:9 |
ICardGui |
高级设置界面的契约 | api/ICardGui.java:9 |
ICardSettingsWrapper |
设置界面的数据提交契约 | api/ICardSettingsWrapper.java:11 |
IRemoteSensor 与 IRangeTriggerable 的接口体为空（IRemoteSensor.java:10-11、IRangeTriggerable.java:9-10），纯标记接口。语义写在各自的 Javadoc 里：实现 IRemoteSensor 后信息屏才会检查目标是否在范围内，且 ICardWrapper.getTarget() / setTarget() 才可被使用（IRemoteSensor.java:3-6）；实现 IRangeTriggerable 使卡片可用于范围触发器（IRangeTriggerable.java:3-6）。
IPanelDataSource 契约
| 方法 | 说明 | 引用 |
|---|---|---|
CardState update(TileEntity panel, ICardWrapper card, int maxRange) |
面板侧更新 | IPanelDataSource.java:26 |
CardState update(World world, ICardWrapper card, int maxRange) |
远程（其他维度）更新 | IPanelDataSource.java:36 |
List<PanelString> getStringData(int displaySettings, ICardWrapper card, boolean showLabels) |
返回要渲染的文本行 | IPanelDataSource.java:50 |
List<PanelSetting> getSettingsList() |
返回可勾选的显示设置项 | IPanelDataSource.java:72 |
UUID getCardType() |
卡片类型标识 | IPanelDataSource.java:79 |
default boolean needsPerTickRefresh() |
是否需要每 tick 在客户端刷新，默认 false | IPanelDataSource.java:88-90 |
needsPerTickRefresh() 是 default 方法，Javadoc 说明其用途是「仅靠封包驱动的缓存失效不足以覆盖的场景」，返回 true 时客户端每 tick 刷新一次卡片显示（IPanelDataSource.java:84-90）。
辅助类
| 类 | 作用 | 引用 |
|---|---|---|
CardHelper |
在任意位置为 ItemStack 取得 ICardWrapper |
api/CardHelper.java:12-22 |
CardState |
卡片状态枚举（5 个值） | api/CardState.java:11 |
PanelString |
一行显示内容：左/中/右三段文本 + 各自颜色 | api/PanelString.java:10-40 |
PanelSetting |
一个显示设置项（标题 + 位序号 + 卡片类型 UUID） | api/PanelSetting.java:11-36 |
NewPanelSetting |
PanelSetting 的子类 |
api/NewPanelSetting.java:5 |
DisplaySettingHelper |
显示设置位集的读写工具 | api/DisplaySettingHelper.java:13 |
BonyDebugger |
作者自用的调试类，输出固定字符串到 stdout | api/BonyDebugger.java:8-20 |
DisplaySettingHelper 早期用整数位掩码实现，受 32 项上限限制，因此改为独立位集类（DisplaySettingHelper.java:8）。它提供多种构造方式：全 true、位字符串、旧版 int 兼容、ByteBuf 网络反序列化、拷贝构造（DisplaySettingHelper.java:19,24,29,43,57,78），以及 getSetting / addSetting / toggleSetting / getAsInteger 等方法（DisplaySettingHelper.java:90,100,112,130）。
CardHelper.getWrapper(ItemStack) 通过反射实例化实现类 shedar.mods.ic2.nuclearcontrol.panel.CardWrapperImpl（CardHelper.java:14,19-20），这样 API 包可以引用实现而不产生编译期循环依赖。反射失败时记录错误日志 "Can't create Nuclear Control Card Wrapper: %s" 并返回 null（CardHelper.java:22-23）—— 调用方需自行判空。
BonyDebugger 的 Javadoc 写明「这是非常严肃的类，不要拿它开玩笑」（BonyDebugger.java:3-4），实现只是向 stdout 打印多行固定字符串 YOLOYOLY...（BonyDebugger.java:15-20）。