公开 API
[!INFO] 源码:
src/main/scala/gcewing/projectblue/下全部public顶层类型
Project Blue 携带一套完整的通用 mod 开发框架（源码注释称 “Greg’s Mod Base”），这才是它对其他 mod 最有价值的产出。框架与本 mod 的具体内容（控制面板）几乎完全解耦。
一、Mod 生命周期骨架
| 类 | 作用 |
|---|---|
BaseMod<CLIENT> |
mod 主类基类。实现 IGuiHandler；持有 modID/config/creativeTab/integrations 列表；按 preInit→init→postInit 分发到所有 BaseIntegration |
BaseModClient<MOD> |
客户端代理基类（@SideOnly 分包惯例） |
BaseIntegration |
扩展点基类。14 个空的 protected void registerXxx() 钩子 + searchForItem / findItem |
ProjectBlue extends BaseMod<ProjectBlueClient> |
实际 mod 主类，覆写 registerItems / registerRecipes / registerMultiParts |
ProjectBlueClient |
客户端代理，覆写 registerRenderers / registerScreens |
BaseIntegration 的 14 个钩子
registerBlocks / registerItems / registerOres / registerRecipes / registerTileEntities / registerRandomItems / registerWorldGenerators / registerContainers / registerEntities / registerVillagers / registerOther / registerScreens / registerRenderers / registerOtherClient，另加 configure / preInit / init / postInit。
BaseMod 在 preInit 调前 6 个 + configure，在 postInit 调后 8 个（含 registerEntities / registerVillagers）。任何 registerXxx 都不必自己写 —— 新整合类只需继承 BaseIntegration 并覆写需要的钩子。
二、注册辅助 API
BaseMod 提供的一站式方法：
| 方法 | 作用 |
|---|---|
addItem(ITEM, name) / newItem(name[, cls]) |
注册物品，自动设 unlocalizedName + textureName + 创造栏 |
addBlock(BLOCK, name[, itemClass]) / newBlock(...) |
注册方块，默认 ItemBlock |
addMultiPart(IPartFactory, String... types) |
注册 multipart（静态） |
addContainer(Enum|int id, Class<? extends Container>) |
注册 GUI 容器（id 来自枚举 ordinal） |
addEntity(Class, name, id, ...) |
实体注册（本 mod 未使用） |
addVillager(name, skin) |
村民注册（本 mod 未使用） |
addTradeHandler(villagerID, handler) |
交易处理器 |
addRandomChestItem(stack, min, max, weight, categories...) |
战利品表 |
addOre(name, block|item) |
注册矿辞条；stackMatchesOre 才是查询 |
newRecipe / newShapelessRecipe / newSmeltingRecipe |
用 ShapedOreRecipe / ShapelessOreRecipe 封装，支持矿辞字符 |
openGui(player, id, world, x, y, z[, param]) |
打开 GUI，param 编入 id 高 16 位 |
searchForItem / findItem |
按 modid:itemid 查找，找不到返回 null（不抛异常） |
stackMatchesOre / blockMatchesOre / itemMatchesOre |
矿辞查询 |
resourceLocation / textureLocation / resourcePath / soundName |
资源定位 |
listResources(subdir) |
运行时扫描 jar 内资源（仅支持 jar: 协议） |
三、网络 API（两套独立机制）
BaseNBTChannel<PACKET_TYPE> — 枚举消息 + NBT 负载
抽象基类，构造即 NetworkRegistry.INSTANCE.newChannel(name, codec)。子类实现 getPacketType()。
| 方法 | 目标 |
|---|---|
sendToServer(type, nbt) |
→ 服务端 |
sendToPlayer(type, nbt, player) |
→ 单玩家 |
sendToAllPlayers(type, nbt) |
→ 全体 |
sendToAllAround(type, nbt, point) |
→ 范围 |
sendToDimension(type, nbt, dimensionId) |
→ 维度 |
子类覆写 onReceiveFromClient(type, nbt, player) / onReceiveFromServer(type, nbt)。
安全特性：ValidatingObjectInputStream.resolveClass 只允许本消息枚举类与 java.lang.Enum，其余抛异常并打 SuspiciousPackets marker 日志。
本 mod 实现：ProjectBlueChannel（通道名 gce.projectblue）。
BaseDataChannel — 字符串消息 + DataOutput 流
构造 (String name, Object... handlers)，多个 handler 共享一条通道。
| 方法 | 说明 |
|---|---|
openServer(msg) |
客户端 → 服务端 |
openPlayer(player, msg) |
服务端 → 玩家 |
openAllPlayers(msg) / openAllAround(point, msg) / openDimension(id, msg) |
广播 |
openServerContainer(msg) / openClientContainer(player, msg) |
容器内消息（自动加 .container. 前缀并转发给当前 Container） |
分发靠注解：handler 方法标 @ServerMessageHandler("msg") / @ClientMessageHandler("msg")，serverDispatch / clientDispatch 用反射扫描 getMethods() 匹配。
本 mod 实现：BaseDataChannel("projectblue.data", this, client)。
四、GUI 框架
BaseGui 是最完整的一块，含大量嵌套类型：
| 类型 | 作用 |
|---|---|
BaseGui.Screen |
GuiContainer + 布局根 |
BaseGui.Root / Group |
容器节点 |
BaseGui.Widget |
控件基类（实现 IWidget） |
BaseGui.MouseCoords |
鼠标位置 |
BaseGui.FieldRef / PropertyRef |
反射绑定的值引用 |
BaseGui.MethodAction |
反射绑定的方法 |
BaseGuiFields.StringField / IntField / FloatField |
文本/整数/浮点输入 |
BaseGuiColor.ColorField / ColorChooser |
颜色选择 |
BaseGuiLayout |
布局工具 |
BaseGuiButtons |
预制按钮 |
BaseGuiContainer |
常用 GuiContainer 子类 |
BaseGuiColor |
16 色调色板 colors[] |
五、方块 / TileEntity 基类
| 类 | 作用 |
|---|---|
BaseContainerBlock<TE> |
BlockContainer 子类基类，构造时自动 GameRegistry.registerTileEntity（吞掉 IllegalArgumentException 容忍重复注册） |
BaseTileEntity |
含 Ticket chunkTicket、区块加载票据、markBlockForUpdate()、playSoundEffect、可覆写的 readContentsFromNBT / writeContentsToNBT |
PBFacePart |
面部 multipart 部件基类。side/rot 状态、getSlotMask() = 1 << side、默认渲染骨架 |
PBFacePart.Factory |
由 Class 反射构造部件并注入 type/side/rot |
PBFacePart.FaceItem |
部件对应的物品，自动 newPart 时计算朝向 |
PBWiredFacePart |
可接线的 PBFacePart，加 connMap（本 mod 无子类） |
ItemMultiPartJ |
CodeChickenLib ItemMultiPart 的纯 Java 重写（“Pure Java version of ItemMultiPart”） |
六、渲染 / 数学工具
| 类 | 作用 |
|---|---|
BaseBlockRenderer<BLOCK> |
ISimpleBlockRenderingHandler 实现 |
PBStaticRenderer / PBDynamicRenderer |
实现 IPBRenderer |
ItemRendererBase |
IItemRenderer 基类 |
PBModel |
从 models/*.json 读模型（ProjectBlue.getModel(name)） |
PBTexture |
纹理包装 |
IPBRenderer |
渲染接口 |
IBlockHighlighting |
放置高亮接口（ControlPanelItem 实现） |
Trans3 / Trans3GL |
变换矩阵（side() / turn() / translate() / rotate() 链式） |
Trans3.turnFor(player, side) |
按玩家视角算朝向 |
Matrix3 / Vector3 |
3×3 矩阵与向量 |
FaceUtils |
邻居通知（正交 + 四斜角） |
BaseUtils / Utils |
字符串 split/join、工具方法 |
BaseColorUtils |
16 色调色板 |
七、NEI 集成 API
| 类型 | 作用 |
|---|---|
INEIRecipeHandler |
接口，只声明 addShapedRecipe(int w, int h, ItemStack out, Object... items) |
NEIRecipeHandler extends ShapedRecipeHandler |
实现该接口 + 转发 loadCraftingRecipes / loadUsageRecipes |
NEIIntegration extends BaseIntegration |
注册 recipe + usage handler |
自定义 IRecipe 通过覆写 addCraftingToNEI(h, result) / addUsageToNEI(h, ingredient) 声明自己在 NEI 中的样子 —— RecipeBase 提供空实现，子类按需覆写。
八、协议枚举与常量
| 枚举 | 取值 |
|---|---|
PBGui |
RednetAdaptor(0)、PneumaticExtractor(1，未启用) |
ControlPanelPart.ControlType |
NONE(0) / BLANK(1) / LEVER(2) / BUTTON(3) / LAMP(4) |
ProjectBlueChannel.Message |
EDIT_CONTROL_PANEL_TEXT / UPDATE_CONTROL_PANEL_TEXT |
BaseDataChannel.ServerMessageHandler |
运行时保留注解 |
BaseDataChannel.ClientMessageHandler |
运行时保留注解 |
ProjectBlue 的公开静态字段（controlPanelItem、miniatureLever/Button/Lamp/Cover、emptySprayCan、sprayCan、channel、dataChannel、mod）以及 getColorName(int) / getModel(String) / getTextures(...) 也是 API 的一部分。
门控
ProjectRed 为硬依赖；MFR 与 NEI 的整合类在对应 mod 缺失时不会被加载。详见 兼容门控。