Skip to content
Qi-Month edited this page Oct 24, 2026 · 2 revisions

Java 集成

本模组的蒸汽接口位于 dev.celestiacraft.steam_letters.api.machine. 按参与深度分为两层:

  • 只交换蒸汽: 暴露标准的 Forge 流体能力, 本模组的泵与设备即可与本方块互相输送, 不依赖本模组的任何类型
  • 沿用蒸汽机器语义: 实现 ISteamStorage 及其子接口, 复用储量管理, 并行加工, 过热蒸汽折算

两层可独立使用. 只做第一层时, 实现方不需要 import 本模组的类.


1. 依赖

本模组未发布 maven 制品, build.gradle 中没有 publish 配置. 依赖本模组时使用本地 jar 或 CurseMaven:

repositories {
	flatDir { dirs "libs" }
}

dependencies {
	implementation fg.deobf("blank:Create-Steam-Letters-<version>-1.20.1:1.20.1")
}

包路径:

import dev.celestiacraft.steam_letters.api.machine.ISteamStorage;
import dev.celestiacraft.steam_letters.api.machine.ISteamBasinMachine;
import dev.celestiacraft.steam_letters.api.machine.ISteamPressMachine;
import dev.celestiacraft.steam_letters.api.machine.heat.IHeatSource;
import dev.celestiacraft.steam_letters.tags.SlFluidTags;

2. 蒸汽的识别方式

本模组不按具体流体实例判断蒸汽, 只查流体标签:

常量 标签
SlFluidTags.STEAM forge:steam
SlFluidTags.SUPERHEATED_STEAM forge:superheated_steam
boolean isSteam(FluidStack stack) {
	return !stack.isEmpty() 
			&& (stack.getFluid().is(SlFluidTags.STEAM)
			|| stack.getFluid().is(SlFluidTags.SUPERHEATED_STEAM));
}

本模组自带的流体是 steam_letters:steam 与 steam_letters:superheated_steam, 两者都带上述标签. 因此只要接受标签, 即可同时接受本模组的蒸汽与其它模组的蒸汽.

3. 只做流体交换

任何通过 getCapability 暴露 ForgeCapabilities.FLUID_HANDLER 的方块都能直接接入, 不需要实现本模组的接口.

本模组的青铜蒸汽泵按以下方式探测端点 (BronzeSteamPumpBlockEntity.java:298):

  1. 取相邻方块在该面的 IFluidHandler
  2. 以 PROBE_AMOUNT 与 FluidAction.SIMULATE 调用 drain
  3. 结果为空或属于蒸汽标签时, 认为该端点可抽取

由此产生两条实现要求:

  • drain 与 fill 的 SIMULATE 分支必须给出真实结果. 始终返回 FluidStack.EMPTY 的模拟实现会让泵判定该端点为真空, 从而不抽取
  • isFluidValid 应接受两种蒸汽标签, 否则外部管道无法向其注入

反方向不受限制: 本模组的设备通过 SteamFluidHandler 暴露单罐 (getTanks() 返回 1), 其它模组的管道与泵可直接抽取.

4. 复用储量与并行

ISteamStorage 定义储量的读, 写, 消耗与并行. 接口不持有状态, 实现类需自行持有 FluidStack 字段.

必须实现的部分:

方法 语义
getSteamStack() 当前储量, 空时返回 FluidStack.EMPTY
setSteamStack(FluidStack) 写入储量, 实现中需调用 setChanged()
getSteamCapacity() 容量, 单位 mB
getSteamConsumption() 单次加工消耗, 单位 mB, 以普通蒸汽计

可覆盖的钩子:

方法 默认行为
getParallelCount() 返回 1, 与机械动力原版一致. 返回 0 或负数表示停止工作
isValidSteam(FluidStack) 接受两种蒸汽标签
getSuperheatedSteamConsumptionMultiplier() 读取配置 general.steam.superheated_steam_consumption_multiplier

可直接调用的工具:

方法 语义
getParallel() 蒸汽不足时为 0
getBatchSize(int available) 本次实际处理的份数
getSteamOperations() 当前储量可支撑的加工次数
hasEnoughSteam() 储量是否够一次加工
consumeSteam() 够则扣除一次并返回 true
fillSteam / drainSteam 单次填充与抽取
steamFluidHandler() 包装为单罐 IFluidHandler

最小实现:

public class MySteamMachineBlockEntity extends SmartBlockEntity implements ISteamStorage {
	private FluidStack steam = FluidStack.EMPTY;
	private final LazyOptional<IFluidHandler> capability = LazyOptional.of(this::steamFluidHandler);

	@Override
	public FluidStack getSteamStack() {
		return steam;
	}

	@Override
	public void setSteamStack(FluidStack stack) {
		steam = stack;
		setChanged();
	}

	@Override
	public int getSteamCapacity() {
		return 8000;
	}

	@Override
	public int getSteamConsumption() {
		return 100;
	}

	@Override
	public <T> LazyOptional<T> getCapability(Capability<T> capability, Direction side) {
		if (capability == ForgeCapabilities.FLUID_HANDLER) {
			return this.capability.cast();
		}
		return super.getCapability(capability, side);
	}

	@Override
	public void invalidateCaps() {
		super.invalidateCaps();
		capability.invalidate();
	}
}

FluidStack 字段的持久化不在接口内, 按父类惯例写入 saveAdditional 与 load, 或 Create 的 write 与 read. 接口的 getCapability 默认实现同样不生效: 父类已是具体方法时, 接口默认值被忽略.

接口的参考实现为 SteamSawBlockEntity, 它只实现 ISteamStorage:

public class SteamSawBlockEntity extends SawBlockEntity implements ISteamStorage {

5. 做成机械动力的加工设备

5.1 工作盆类

ISteamBasinMachine 在 ISteamStorage 之上增加按并行数循环执行工作盆配方. 必须实现 getBasinRecipe(), getBasin(), matchBasinRecipe(Recipe<C>), continueWithPreviousRecipe(), sendData().

默认的 applyBasinRecipe() 已经处理并行循环, 蒸汽扣除与输入罐同步, 通常无需重写. 需要扩展时覆盖 onBasinRecipeApplied(int applied).

父类已有具体实现时, 接口的默认实现会被忽略. 因此在继承 MechanicalMixerBlockEntity 这类父类时, 必须以 public 覆盖该方法并委托给接口:

@Override
public void applyBasinRecipe() {
	ISteamBasinMachine.super.applyBasinRecipe();
}

参考实现 SteamMixerBlockEntity.java:96 与 SteamHammerBlockEntity.java:101.

5.2 压床类

ISteamPressMachine 在 ISteamStorage 之上实现 PressingBehaviour.PressingBehaviourSpecifics. 必须实现 getRecipe(ItemStack), getPressingBehaviour(), getSpeed(), 其余有默认值.

两条约束:

  • canProcessInBulk() 必须返回 false. 返回 true 时机械动力走自身的并行路径, 蒸汽侧的并行不会触发
  • 继承 MechanicalPressBlockEntity 时, canProcessInBulk, tryProcessOnBelt, tryProcessInWorld 需委托 ISteamPressMachine.super 才生效, 见 SteamHammerBlockEntity.java:106, :111, :116

6. 做成热源

IHeatSource 位于 api.machine.heat, 要求实现 getHeat(), getMaxHeat(), isBurningFuel(), 并自带 getHeatRatio() 默认实现.

锅炉不通过能力通道读取热源, 只取正下方方块的方块实体并判断是否实现该接口 (AbstractBoilerBlockEntity.java:127). 因此:

  • 不需要注册任何能力, 方块实体实现接口即被识别
  • 只支持正下方一格位移, 不支持管道或任意距离
  • 热量刻度与 getMaxHeat() 一致, 返回值由实现方自行决定

参考实现为 AbstractBurnerBlockEntity, 它同时实现 IHeatSource 与 IHaveGoggleInformation.

7. 应力

不要将非本模组的方块加入本模组的应力配置. SlStress.java:94 对非本模组方块直接抛出异常:

IllegalStateException("Non-CreateLettersSteam blocks cannot be added to CreateLettersSteam config.")

需要应力参与机械动力应力网络时, 使用 Create 的 BlockStressValues.IMPACTS 与 BlockStressValues.CAPACITIES 注册提供者.

本模组引擎的应力由方块注册参数决定, 不走 server.toml 中的 stressValues. 这一点同样适用于 KubeJS 注册的引擎, 详见 KubeJS 集成.

8. 让同一方块实体类型服务多个方块

SteamEngineSpec 与 SteamEngineDriveSpec 用 IntSupplier 与 DoubleSupplier 承载参数, 而不是裸数值. 原因是方块注册时配置文件尚未加载, 注册期只能保存取值方式.

SteamEngineSpec spec = SteamEngineSpec.of((builder) -> {
		builder.capacity(() -> MyConfig.boilerCapacity.get())
			.production(() -> MyConfig.boilerProduction.get());
});

ISteamEngineBlock 由方块实现, 提供 getEngineSpec(). 参数挂在方块而非方块实体上, 因为同一个 BlockEntityType 会服务多个参数不同的方块.

只在需要这种拆分时才使用上述两个类. 一个方块对应一个方块实体类型时, 直接持有字段即可.

9. 常见问题

  • 泵不抽取该方块: drain 的 SIMULATE 分支未给出真实结果
  • 外部管道无法注入: isFluidValid 拒绝了蒸汽标签
  • 并行不生效: canProcessInBulk() 返回了 true
  • 覆盖 applyBasinRecipe 后没有扣蒸汽: 未委托 ISteamBasinMachine.super
  • 换算过热蒸汽后消耗量不变: 覆盖了 getCurrentSteamConsumption() 却没有沿用默认的倍率折算
  • 注册期读到的配置值为 0: 配置尚未加载, 改用 supplier 形式

相关页面: KubeJS 集成, KubeJS API 参考, 返回首页.

附: 维护边界

本文只记录接口契约与不可见约束, 不记录字段清单与具体数值:

  • 方法清单以 api/machine 下的源码为准, 本文只写必须实现的成员与容易踩空的语义
  • 数值 (容量, 产量, 消耗, 倍率) 以配置与注册类为准, 本文不重复
  • 新增设备时, 若其接口用法与上文某一类一致, 不需要修改本文; 只有当接口契约本身变化时才更新对应小节

需要查看的源码入口:

Clone this wiki locally