Repository navigation
Java
本模组的蒸汽接口位于 dev.celestiacraft.steam_letters.api.machine. 按参与深度分为两层:
- 只交换蒸汽: 暴露标准的 Forge 流体能力, 本模组的泵与设备即可与本方块互相输送, 不依赖本模组的任何类型
- 沿用蒸汽机器语义: 实现
ISteamStorage及其子接口, 复用储量管理, 并行加工, 过热蒸汽折算
两层可独立使用. 只做第一层时, 实现方不需要 import 本模组的类.
本模组未发布 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;本模组不按具体流体实例判断蒸汽, 只查流体标签:
| 常量 | 标签 |
|---|---|
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, 两者都带上述标签. 因此只要接受标签, 即可同时接受本模组的蒸汽与其它模组的蒸汽.
任何通过 getCapability 暴露 ForgeCapabilities.FLUID_HANDLER 的方块都能直接接入, 不需要实现本模组的接口.
本模组的青铜蒸汽泵按以下方式探测端点 (BronzeSteamPumpBlockEntity.java:298):
- 取相邻方块在该面的
IFluidHandler - 以
PROBE_AMOUNT与FluidAction.SIMULATE调用drain - 结果为空或属于蒸汽标签时, 认为该端点可抽取
由此产生两条实现要求:
-
drain与fill的SIMULATE分支必须给出真实结果. 始终返回FluidStack.EMPTY的模拟实现会让泵判定该端点为真空, 从而不抽取 -
isFluidValid应接受两种蒸汽标签, 否则外部管道无法向其注入
反方向不受限制: 本模组的设备通过 SteamFluidHandler 暴露单罐 (getTanks() 返回 1), 其它模组的管道与泵可直接抽取.
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 {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.
ISteamPressMachine 在 ISteamStorage 之上实现 PressingBehaviour.PressingBehaviourSpecifics. 必须实现 getRecipe(ItemStack), getPressingBehaviour(), getSpeed(), 其余有默认值.
两条约束:
-
canProcessInBulk()必须返回 false. 返回 true 时机械动力走自身的并行路径, 蒸汽侧的并行不会触发 - 继承
MechanicalPressBlockEntity时,canProcessInBulk,tryProcessOnBelt,tryProcessInWorld需委托ISteamPressMachine.super才生效, 见SteamHammerBlockEntity.java:106,:111,:116
IHeatSource 位于 api.machine.heat, 要求实现 getHeat(), getMaxHeat(), isBurningFuel(), 并自带 getHeatRatio() 默认实现.
锅炉不通过能力通道读取热源, 只取正下方方块的方块实体并判断是否实现该接口 (AbstractBoilerBlockEntity.java:127). 因此:
- 不需要注册任何能力, 方块实体实现接口即被识别
- 只支持正下方一格位移, 不支持管道或任意距离
- 热量刻度与
getMaxHeat()一致, 返回值由实现方自行决定
参考实现为 AbstractBurnerBlockEntity, 它同时实现 IHeatSource 与 IHaveGoggleInformation.
不要将非本模组的方块加入本模组的应力配置. SlStress.java:94 对非本模组方块直接抛出异常:
IllegalStateException("Non-CreateLettersSteam blocks cannot be added to CreateLettersSteam config.")
需要应力参与机械动力应力网络时, 使用 Create 的 BlockStressValues.IMPACTS 与 BlockStressValues.CAPACITIES 注册提供者.
本模组引擎的应力由方块注册参数决定, 不走 server.toml 中的 stressValues. 这一点同样适用于 KubeJS 注册的引擎, 详见 KubeJS 集成.
SteamEngineSpec 与 SteamEngineDriveSpec 用 IntSupplier 与 DoubleSupplier 承载参数, 而不是裸数值. 原因是方块注册时配置文件尚未加载, 注册期只能保存取值方式.
SteamEngineSpec spec = SteamEngineSpec.of((builder) -> {
builder.capacity(() -> MyConfig.boilerCapacity.get())
.production(() -> MyConfig.boilerProduction.get());
});ISteamEngineBlock 由方块实现, 提供 getEngineSpec(). 参数挂在方块而非方块实体上, 因为同一个 BlockEntityType 会服务多个参数不同的方块.
只在需要这种拆分时才使用上述两个类. 一个方块对应一个方块实体类型时, 直接持有字段即可.
- 泵不抽取该方块:
drain的SIMULATE分支未给出真实结果 - 外部管道无法注入:
isFluidValid拒绝了蒸汽标签 - 并行不生效:
canProcessInBulk()返回了 true - 覆盖
applyBasinRecipe后没有扣蒸汽: 未委托ISteamBasinMachine.super - 换算过热蒸汽后消耗量不变: 覆盖了
getCurrentSteamConsumption()却没有沿用默认的倍率折算 - 注册期读到的配置值为 0: 配置尚未加载, 改用 supplier 形式
相关页面: KubeJS 集成, KubeJS API 参考, 返回首页.
本文只记录接口契约与不可见约束, 不记录字段清单与具体数值:
- 方法清单以
api/machine下的源码为准, 本文只写必须实现的成员与容易踩空的语义 - 数值 (容量, 产量, 消耗, 倍率) 以配置与注册类为准, 本文不重复
- 新增设备时, 若其接口用法与上文某一类一致, 不需要修改本文; 只有当接口契约本身变化时才更新对应小节
需要查看的源码入口: