公开 API 接口

openmods.api 包是 OpenModsLib 对外承诺稳定的 19 个接口 + 1 个注解，覆盖方块/容器的事件回调、物品堆叠交互与 GUI 约定。这些接口是 OpenBlocks、OpenComputers、OpenPeripheral 等下游 mod 与 OpenModsLib 之间的实际契约层 —— OpenModsLib 通过 IncludingClassVisitor（见类注入与 include）把这些接口混入下游的类中。

基本信息

属性	值
包路径	`openmods.api`
接口数	19
注解数	1（`@VisibleForDocumentation`）
文件总数	20
泛型接口数	2（`IValueProvider<T>`、`IValueReceiver<T>`）
被 OpenModsLib 自身实现的接口	0（全部供下游 mod 实现）

功能

方块生命周期回调（8 个）

这组接口对应 Minecraft 中方块被放置、破坏、激活时的回调点，OpenModsLib 把它们定义为可混入的接口，下游只需在类上标注 @IncludeInterface 即可获得回调：

接口	方法	触发时机
`IPlaceAwareTile`	`onBlockPlacedBy(EntityPlayer player, ForgeDirection side, ItemStack stack, float hitX, float hitY, float hitZ)`	玩家放置方块后
`IPlacerAwareTile`	`onBlockPlacedBy(EntityLivingBase placer, ItemStack stack)`	任意实体放置方块后（更通用，不含朝向与命中点）
`IBreakAwareTile`	`onBlockBroken()`	方块被破坏后
`IActivateAwareTile`	`onBlockActivated(EntityPlayer player, int side, float hitX, float hitY, float hitZ)`	玩家右键方块
`INeighbourAwareTile`	`onNeighbourChanged(Block block)`	邻接方块变化
`INeighbourTeAwareTile`	`onNeighbourTeChanged(int x, int y, int z)`	邻接 TileEntity 变化（带坐标）
`IAddAwareTile`	`onAdded()`	TileEntity 被加入世界
`ISelectionAware`	`onSelected(World world, int x, int y, int z, DrawBlockHighlightEvent evt)`	玩家用选择工具框选方块

IPlaceAwareTile 与 IPlacerAwareTile 方法名相同但签名不同，前者带 ForgeDirection 与命中坐标、接收 EntityPlayer，后者接受任意 EntityLivingBase。两者可同时实现，但同名方法会触发 IncludingClassVisitor.visitEnd 的冲突校验（见类注入）—— 实现其中之一时，另一接口的同名方法必须标 @IncludeOverride。

ISelectionAware 依赖 Forge 的 DrawBlockHighlightEvent，是该包中唯一非原版 API 的接口。

掉落物控制（2 个）

接口	方法	说明
`ICustomBreakDrops`	`addDrops(List<ItemStack> drops)`	破坏时追加掉落物
`ICustomHarvestDrops`	`suppressNormalHarvestDrops()` + `addHarvestDrops(@Nullable EntityPlayer player, List<ItemStack> drops)`	收获时追加掉落物，并可抑制原版掉落

ICustomHarvestDrops 是二者中唯一提供抑制原版行为开关的接口，且其方法未加 public 修饰（接口内隐式 public）。

容器与 GUI（2 个）

接口	方法	说明
`IInventoryContainer`	`getInternalInventories()`	暴露内部所有 `IInventory`，供自动化与 GUI 统一访问
`IHasGui`	`getServerGui(EntityPlayer)` / `getClientGui(EntityPlayer)` / `canOpenGui(EntityPlayer)`	容器 GUI 的双端约定

IHasGui 的三方法全部返回 Object 而非具体 GUI 类型 —— 这是刻意的解耦：服务端容器与客户端 GuiScreen 类型不同，统一用 Object 承载，由调用方转型。canOpenGui 允许在打开前拒绝访问。

物品与图标（2 个）

接口	方法	说明
`ICustomPickItem`	`getPickBlock()`	覆盖 `Ctrl+滚轮` 选取的物品堆叠
`IIconProvider`	`getIcon(ForgeDirection rotatedDir)`	按旋转方向提供图标

IIconProvider 支持 6 个 ForgeDirection 参数，是包中唯一按方向分派的接口。

值传递（4 个）

接口	方法	说明
`IValueProvider<T>`	`T getValue()`	只读值源
`IValueReceiver<T>`	`void setValue(T value)`	只写值汇
`IInventoryCallback`	`onInventoryChanged(IInventory inventory, int slotNumber)`	容器内容变化回调
`ISurfaceAttachment`	`getSurfaceDirection()`	返回所依附的表面朝向

IValueProvider<T> 与 IValueReceiver<T> 是一对互补的泛型接口，构成最轻量的数据传递协议，常用于方块与 GUI 之间传递单个值。

其它（1 个）

接口	方法	说明
`IProxy`	`preInit()` / `init()` / `postInit()` / `registerRenderInformation()`	客户端/服务端代理的标准四阶段生命周期

IProxy 是 IOpenModsProxy（openmods.proxy 包）之外更通用的代理契约，四个方法对应 FML 的三阶段初始化加渲染注册。

变换器结果回调（1 个）

接口	方法	说明
`IResultListener`	`onSuccess()` / `onFailure()`	字节码变换结果反馈

IResultListener 被 OpenModsClassTransformer.createResultListener（src/main/java/openmods/core/OpenModsClassTransformer.java:76）实现，用于把 6 个 coremod 补丁的状态从 ACTIVATED 推进到 FINISHED 或 FAILED，详见coremod 补丁。

文档可见性注解

@VisibleForDocumentation（src/main/java/openmods/api/VisibleForDocumentation.java）标注在类型上（@Target(ElementType.TYPE)），运行时保留。作用是让工具能识别出「本应在此但为文档目的保留」的占位类型。openmods.api 包内无任何类使用它。

数值

数值名	值
接口总数	19
注解总数	1
方块生命周期回调接口	8
掉落物控制接口	2
容器 / GUI 接口	2
物品 / 图标接口	2
值传递接口	4
代理接口	1（`IProxy`）
泛型接口	2
接口中方法总数	27
依赖 Forge 专有 API 的接口	1（`ISelectionAware`，用 `DrawBlockHighlightEvent`）

交互

本包的接口不被 OpenModsLib 主动调用 —— 它们是等待下游 mod 实现的契约。生效链路为：

下游 mod 的类标注 @IncludeInterface(SomeInterface.class)（src/main/java/openmods/include/IncludeInterface.java:9）
coremod 阶段 IncludingClassVisitor 读入 FML 的 ASMDataTable（src/main/java/openmods/core/OpenModsClassTransformer.java:230-235）
类加载时合成转发方法，实现接口（见类注入）

因此这些接口对玩家完全不可见；玩家可感知的是它们带来的行为（放置回调、破坏掉落、GUI 交互等）。