
HyDustry 库
HyDustry Lib 是一个专注于 Java 开发工具和节点编辑器的模组;它添加了组件,并利用一个名为“keys”的系统(基于标签,即 KBT),允许用户通过节点编辑器修改对象的行为。

HyDustry Lib
面向 Java 和节点编辑器的开源库 -> 开源 [Github]
注意!
最初,此库是作为 HyDustry 的依赖项创建的。许多 Java 函数已过时——尤其是那些从其引用的类中获取组件的函数——并且随着项目转变为开源模组,标签系统将被移除,届时该模组将作为此库的依赖项。
面向 Java 程序员
class HyDustryLib
HyDustryLib.AddConsumerMachineOperationType(String Name, Consumer<ConsumerMachineComponent> Function):
为机器添加一种新的操作格式。
示例:
HyDustryLib.AddConsumerMachineOperationType("Essence Extractor", <classname>::Execute);
HyDustryLib.AddConveyorOperationType(String Name, Consumer<ConveyorTransporterComponent> Function):
在映射中添加或替换传送器的操作函数。
示例:
HyDustryLib.AddConveyorOperationType("Rotator Conveyor", <classname>::Execute);
HyDustryLib.get()
为机器添加一种新的操作格式。
示例:
HyDustryLib.getConsumerMachineComponentType()
返回 getConsumerMachineComponentType 的已注册类型。
HyDustryLib.getConveyorTransporterComponentType()
返回 getConveyorTransporterComponentType 的已注册类型。
HyDustryLib.getHarvestingEngineComponentType()
返回 getHarvestingEngineComponentType 的已注册类型。
主要组件
ConsumerMachineComponent
表示一台消耗材料并产出产品的机器。其可配置字段包括 ManufacturingTime、RequireFuel、RequireEnergy、InputItems、OutputItems 和 OperationType。
ExecuteBehaviour():执行注册到OperationType的操作;如果未找到操作,则使用默认行为。ExecuteBehaviourDefault():校验时间、材料、燃料和容器;消耗资源,并在有空间时交付配置的产品。InitializeConfiguration(Map<String, String[]>):配置操作类型,并将方块的标签存储在组件中。GetItemsOutput():根据机器的配置构建输出产品列表。ItemsVerification(boolean):检查所需材料是否可用。processItems(boolean):消耗配方或当前升级所需的材料。getAvailableFuelId()和processFuel(String):检查并消耗配置的燃料。ManufacturingAvailability()和RenewManufacturingAvailability(Long):检查并更新制造冷却/等待时间。GetInputItemsHyDustryComponent()和GetOutputItemsHyDustryComponent():返回组件的输入和输出容器。
ConveyorTransporterComponent
表示传送带的状态。Velocity 控制向前移动;Progress 表示任务的完成状态;ItemsDetected 和 LookingBehaviour 表示物体检测和当前搜索状态。
HarvestingEngineComponent
表示一台收割引擎。它存储 Range、Interval、当前阶段、灌溉时机,以及以下触发动作:Water、Harvest、Fertilize 和 Accelerate。
示例操作:Extractor
Extractor.Execute(ConsumerMachineComponent)
为消耗型机器内置的操作。扫描配置的位置,识别主要资源,计算输出及其倍率,消耗所需材料,并在输出容器有空间时存储产品。
HyDustryLib.AddConsumerMachineOperationType("Essence Extractor", Extractor::Execute);
已实现的工具类
EssentialsUtils
getBlockType(World, Vector3i):查询给定位置的方块类型。getBlockSection(World, Vector3i):获取包含该位置的区块段。getBlockRef(World, Vector3i):获取方块的实体引用。getBlockRotation(World, Vector3i):获取方块的旋转。getGlobalPosition(...):将方块的本地坐标转换为世界坐标。
RailsHyDustryLib
OrientRails(Vector3d[], int):旋转路径点以与方块的朝向对齐。OrientGlobalPositions(Vector3d[], int):变换相对于方块朝向的偏移。RailsCalculateNextPosition(Vector3d[], double, int):根据进度和平滑度计算路径上的位置。TagsPathsConversion(Map):将路径标签转换为向量。ConvertingTagstoArrays(Map, String)和ConvertingTagsPositionstoArrays(Map, String):将坐标标签转换为向量数组。
FarmingHyDustryLib
ProccesingCoopsInRange(...):处理引擎范围内的方块,并应用任何已启用的照料和收割动作。AccelerateGrowthInBlock(...):推进作物进入下一生长阶段。WateringInBlock(...):延长方块中的灌溉持续时间。耕地。WateringAndFetilizedInBlock(...):浇灌并施肥耕地。FetilizedInBlock(...):为耕地施肥。UpdateGrowthInBlock(...):为方块安排生长更新。
HarvestingHyDustryLib
HarvestInSimpleContainer(...):收集方块的掉落物,并更新方块或作物的生长阶段。HarvestValidationGatheringInContainer(...):检查掉落物是否可以存储在容器中。HarvestBlockValidation(...):检查方块是否具有有效的收割配置。
物品容器
InputItemsHyDustryLib、OutputItemsHyDustryLib 和 SimpleItemContainerHyDustryLib 提供检查物品堆叠是否能放入、获取最后一个物品以及从库存中移除物品的操作。输入和输出校验函数还允许根据方块配置的位置定位容器。
未包含的元素
OrientRailsObsolete及标记为过时的函数:已被当前朝向函数取代。- 过时的扫描器偏移和大小函数:当前扫描器使用配置的位置。
RaycastHyDustryLib:空类。ConveyorBelt.Execute:无实现的方法。- 无动作的模拟和初始化方法:这些方法不会为模组贡献任何特定行为。
Lib 文件夹中工具的实用指南
使用这些函数之前
本指南仅涵盖位于 src/main/java/Hytale/Modification/hydustrylib/Lib 中的类。该库仍在演进:一些从方块获取组件的函数依赖于当前的标签系统,可能会发生变化。使用前请验证引用和组件,并查阅你所编译项目所用的 HyDustry Lib 特定版本的 API 文档。
入门
Lib 中的类主要作为静态方法的容器。它们通过类名调用,无需创建实例。示例假设你的模组从适当的服务器上下文中获取 World、CommandBuffer 和方块引用。
import Hytale.Modification.hydustrylib.Lib.EssentialsUtils;
import Hytale.Modification.hydustrylib.Lib.InputItemsHyDustryLib;BlockType type = EssentialsUtils.getBlockType(world, blockPosition);
ItemContainerBlock input =
InputItemsHyDustryLib.GetInputItemsComponent(world, blockPosition);
if (type != null && input != null) {
// 在服务器上下文中使用方块及其库存。
}
如果方块、其区块段或其组件不存在,若干查询将返回 null。在访问这些结果之前请先检查。修改方块、库存或实体的函数必须在世界及其存储的适当上下文中执行。
方块与坐标工具
EssentialsUtils
用于方块和位置转换的低级查询。Vector3i 类型表示整数方块坐标;getGlobalPosition 的结果是世界位置。
getBlockType(World world, Vector3i Position):返回该位置的BlockType,如果无法解析则返回null。getBlockSection(World world, Vector3i Position):返回包含该位置的BlockSection,或null。getBlockRef(World world, Vector3i Position):返回与方块关联的实体引用,或null。getBlockRotation(World world, Vector3i Position):返回旋转索引;如果无法获取区块段则返回-1。getGlobalPosition(BlockStateInfo, CommandBuffer<ChunkStore>):使用方块状态的索引和区块段计算世界位置。getGlobalPosition(Vector3ic localPosition, BlockStateInfo, CommandBuffer<ChunkStore>):转换显式本地位置;如果无法获取区块段则返回null。
示例:查询类型和旋转
BlockType type = EssentialsUtils.getBlockType(world, position);
int rotation = EssentialsUtils.getBlockRotation(world, position); if (type != null && rotation >= 0) {
Map<String, String[]> tags = type.getData().getRawTags();
}
最后一行要求 type.getData() 不为 null。位于已加载区块段之外的坐标可能无法产生有效引用或结果。
FillerBlocksHyDustryLib
CalculateRealPositionUsingFillerBlocks(World world, Vector3i Position):如果该位置属于填充方块,则尝试返回主体实心方块的位置。如果无法解析,则返回原始位置。
建议在查询可能属于多方块结构的方块之前应用此函数。
Vector3i realPosition =
FillerBlocksHyDustryLib.CalculateRealPositionUsingFillerBlocks(world, hitPosition);
BlockType type = EssentialsUtils.getBlockType(world, realPosition);
RailsHyDustryLib:朝向与移动
OrientRails(Vector3d[] points, int direction):返回围绕方块水平中心旋转后的点的副本。水平方向索引映射到四个朝向;介于 8 到 63 之间的一些索引还会反转 Y 坐标。OrientGlobalPositions(Vector3d[] points, int direction):旋转相对位移。用于变换围绕方块的偏移,而非用于定向绝对世界空间点。RailsCalculateNextPosition(Vector3d[] rotatedPoints, double progressPercent, int smoothing):在前三个点之间进行插值。进度被限制在 0–100;平滑度被限制在 0–10。如果提供的点少于三个,则返回中心(0.5, 0.5, 0.5)。TagsPathsConversion(Map<String, String[]> Tags):将HyDustryUtility.Paths标签转换为向量。如果标签缺失或为空,则返回单个中心点。ConvertingTagstoArrays(Map, String Tag):将HyDustryUtility.<Tag>标签读取为逗号分隔的坐标(例如1,0,0)。如果不存在任何值则返回null。ConvertingTagsPositionstoArrays(Map, String Tag):与上述等效,但处理可能被括号括起来的坐标。vectorArrayToString(Vector3d[] vectors):将数组转换为文本格式,坐标三元组用括号括起;null或空数组转换为[]。
示例:获取物体沿路径的位置
Map<String, String[]> tags = blockType.getData().getRawTags();
Vector3d[] path = RailsHyDustryLib.TagsPathsConversion(tags);
Vector3d[] orientedPath = RailsHyDustryLib.OrientRails(path, rotation);
Vector3d pointOnBlock =
RailsHyDustryLib.RailsCalculateNextPosition(orientedPath, progressPercent, 0);Vector3d worldPosition = new Vector3d(position.x, position.y, position.z)
.add(pointOnBlock.x, pointOnBlock.y, pointOnBlock.z);
路径必须包含至少三个点才能进行插值。对于相对于机器的偏移,请使用 OrientGlobalPositions 而非 OrientRails;这两个函数采用不同的约定。
不要使用:OrientRailsObsolete 标记为 @Deprecated。请使用 OrientRails。
用于查找方块组件的工具
以下校验器使用方块的旋转、预期偏移以及(如果存在)HyDustryUtility.Vertical 标签来推导相邻位置。然后它们解析填充方块并搜索所需组件。这些工具便于用于配置了 HyDustry Lib 预期标签的方块;对于新系统,建议维护你自己的引用并直接查询存储。
InputItemsHyDustryLib
InputItemsHyDustryValidatorComponent(World, int, Vector3i, Map<String, String[]>, Vector3d):给定世界、旋转、初始位置、标签和预期偏移,尝试获取输入ItemContainerBlock。如果未找到方块或组件则返回 null。GetInputItemsComponent(World, Vector3i):直接从绝对位置获取输入容器。ValidationItemForAdding(ItemContainerBlock, ItemStack):检查是否有可用槽位或具有相同标识符且有空间的物品堆叠。getLastItem(ItemContainerBlock):返回最靠近库存末尾的已占用堆叠;不创建副本。removeLastItem(ItemContainerBlock):移除最靠近库存末尾的整个堆叠。
OutputItemsHyDustryLib
OutputItemsHyDustryValidatorComponent(World, int, Vector3i, Map<String, String[]>, Vector3d):根据朝向、标签和偏移定位输出容器。GetOutputItemsComponent(World, Vector3i):获取绝对位置的容器。ValidationItemForAdding(ItemContainerBlock, ItemStack):检查物品是否可以放入兼容的槽位或堆叠。getLastItem(ItemContainerBlock, int count):从最后占用的堆叠中返回最多count个物品的干净副本。不修改库存。removeLastItem(ItemContainerBlock, int count):从最后占用的堆叠中移除最多count个物品,并更新或清空该槽位。
ItemContainerHyDustryLib
ItemContainerBlockValidatorComponent(World, int, Vector3i, Map<String, String[]>, Vector3d):在指定的相对和定向位置搜索ItemContainerBlock。如果方块或组件不可用则返回 null。
ComponentsGenericHyDustryLib
InputItemsHyDustryValidatorComponent(World, int, Vector3i, Map<String, String[]>, Vector3d):使用相同的相对定位规则返回相邻方块的Ref<ChunkStore>引用。它不返回库存组件本身;你必须使用该引用查询存储。
ConsumerMachineHyDustryLib
ConsumerMachineValidatorComponent(World, int, Vector3i, Map<String, String[]>, Vector3d):在相对位置搜索消耗型机器并返回其ConsumerMachineComponent,如果不存在则返回 null。
以 ValidatorComponent 结尾的函数执行查找并可能返回 null。它们不会创建或添加组件。使用前请确保参数对应于基础方块及其朝向。
相对容器示例
ItemContainerBlock input =
InputItemsHyDustryLib.InputItemsHyDustryValidatorComponent(
world,
rotation,
machinePosition,
rawTags,
new Vector3d(0, 0, -1)
);if (input != null && input.getItemContainer() != null) {
// 在有效的服务器上下文中查询或修改库存。
}
当前校验器从标签中读取 HyDustryUtility.Vertical 以确定垂直位置。如果你的模组不使用这些标签,最好使用 GetInputItemsComponent、GetOutputItemsComponent 或你自己的存储查询。
库存
SimpleItemContainerHyDustryLib
ValidationItemForAdding(SimpleItemContainer, ItemStack):如果找到空槽位或未满的相同物品堆叠则返回 true。getLastItem(SimpleItemContainer, int count):从最后一个堆叠中返回最多count个单位数的干净副本。如果count不为正或没有物品,则返回 null。removeLastItem(SimpleItemContainer, int count):从最后占用的堆叠中移除最多count个单位数,如果找到要修改的堆叠则返回 true。
选择合适的工具
- 对于具有 HyDustry 输入组件的容器,使用
InputItemsHyDustryLib。 - 使用
OutputItemsHyDustryLib查询、复制或从输出中移除部分数量。 - 当你已经拥有
SimpleItemContainer时使用SimpleItemContainerHyDustryLib——例如,一次运输一个单位。
示例:在检查前移除一个单位而不修改它
ItemStack preview =
SimpleItemContainerHyDustryLib.getLastItem(container, 1);if (preview != null && isValidDestination(preview)) {
boolean removed =
SimpleItemContainerHyDustryLib.removeLastItem(container, 1);
if (removed) {
// 将 preview 转移到目的地。
}
}
ValidationItemForAdding 仅检查是否有容量;它不会添加物体或预留空间。在验证和添加之间,如果其他操作可能修改库存,请重新验证状态。
对象实体
EntityHyDustryLib
EntityIsValid(Ref<EntityStore> ref):检查引用是否有效、具有 Store,并拥有UUIDComponent。ToggleBehaviourInteractionItems(TransformComponent transform, boolean BH, Store<EntityStore> store, Ref<EntityStore> ref):如果BH == false,则添加防止合并和拾取的组件;如果BH == true,则移除它们并调整物体的位置。
此函数直接修改实体的组件和变换。仅在适合临时更改物体行为时调用它。
农业与收割
FarmingHyDustryLib
ProccesingCoopsInRange(CommandBuffer<ChunkStore>, HarvestingEngineComponent, Vector3i, int range, int Phase):遍历引擎周围的区域,并根据组件的设置应用灌溉、施肥、生长加速或收割。AccelerateGrowthInBlock(CommandBuffer<ChunkStore>, Ref<ChunkStore>, World, BlockType):推进作物向下一阶段生长。WateringInBlock(CommandBuffer<ChunkStore>, Ref<ChunkStore>, World, float WateringTime):延长灌溉持续时间并延迟耕地的退化。WateringAndFertilizedInBlock(...):执行灌溉并将土壤标记为已施肥。FertilizedInBlock(CommandBuffer<ChunkStore>, Ref<ChunkStore>):将耕地标记为已施肥。UpdateGrowthInBlock(CommandBuffer<ChunkStore>, Ref<ChunkStore>, World):为作物组件安排更新。AccelerateCropGrowth(Vector3i, World):直接获取方块引用并推进生长到下一阶段的变体;标记为@Insecure。ScheduleInstantUpdate(CommandBuffer<ChunkStore>, Ref<ChunkStore>, World):为方块安排新的 tick;标记为@Insecure。
标记为 @Insecure 的函数需要特别注意方块引用和组件。当系统已有可用的 CommandBuffer 时,优先使用接受 CommandBuffer 的变体。
HarvestingHyDustryLib
HarvestInSimpleContainer(Vector3i blockPosition, World world, ItemContainerBlock container):获取收割掉落物并将其添加到库存;它可能会将作物重置到其后续生长阶段或将收割的方块替换为空气。返回一个布尔值表示收割操作的结果。HarvestValidationGatheringInContainer(Vector3i, World, ItemContainerBlock):检查收割配置以及库存是否能接受任何掉落物。HarvestBlockValidation(Vector3i, World):检查方块是否具有掉落配置,以及其作物配置是否允许被处理。
收割前,请检查方块类型和库存。收割函数可能同时修改世界和容器;不要将其用作只读查询。
API 注解
@safe(reason = "..."):源代码级注解,用于标识库认为稳定的方法或构造函数。@Insecure(reason = "..."):源代码级注解,用于警告方法或构造函数需要谨慎使用。
这些注解不替代运行时验证,也不会自动应用任何保护。它们的保留策略为 SOURCE,意味着它们在运行时不会作为元数据保留。
当前无公共用途的类
RaycastHyDustryLib:空类;不提供任何函数。OrientRailsObsolete:过时方法;请改用OrientRails。
面向节点编辑器程序员
使用 Hytale 节点编辑器配置方块、组件和标签的指南
范围与警告
本指南概述 HyDustry Lib 中当前代码读取或注册的键和字段。标签表示方块数据,而组件是通过编辑器添加到方块的独立数据元素。并非每个方块都需要所有标签。此处未提及的任何键在当前审查的代码中均未使用。
重要:当前代码查找以 HyDustryUtility. 开头的键。名为 HyDustry.Behaviour 的键不等同于 HyDustryUtility.Behaviour,不会触发本指南中描述的传送带行为。
标签的表示方式
HyDustry Lib 以 Map<String, String[]> 的形式接收方块标签:每个条目由一个文本键映射到一个文本值数组组成。在 Hytale 源文件中,格式如下:
{
"HyDustryUtility.Machine.Behaviour": ["Essence Extractor"],
"HyDustryUtility.Machine.Scanner.Positions": ["0,0,-1", "1,0,-1"]
}
- 标签名称及其数组内的所有元素都是字符串,即使它们表示数字或布尔值。
- 在并行列表中值的顺序很重要:索引 0 处的元素对应其关联标签索引 0 处的值。
- 坐标写作
x,y,z。小数使用小数点——例如0.5,0.5,1.0。 - 不要在 JSON 中包含注释。本指南中包含
//的片段仅用于解释,不属于数据的一部分。 - “标志”型标签只需存在即可激活,无论其包含的文本是什么。对于这些标签,建议使用
["true"]。
经验法则:标签 vs. 组件
标签:描述代码从方块原始标签中读取的配置。示例包括配方、扫描器位置、路径和输入/输出偏移。
组件:存储 HyDustry Lib 系统的状态和选项。插件注册了三个组件:ConsumerMachineComponent、ConveyorTransporterComponent 和 HarvestingEngineComponent。通过编辑器将这些组件添加到适当的方块,并在组件面板中配置其字段。不要将这些字段转换为标签,除非代码明确指示它读取某个标签。
下面的组件示例显示的是由 codec 注册的可编辑字段,而非整个 Hytale 方块文件包装器。节点编辑器序列化或引用组件的确切方式取决于 Hytale 方块格式,不应从标签映射中推断。
已识别标签摘要
| 完整标签 | 用途 | 预期类型 |
|---|---|---|
HyDustryUtility.Machine.Behaviour |
机器操作名称,例如 Essence Extractor。 |
字符串数组中的一个名称。 |
HyDustryUtility.Machine.Output.Items / HyDustryUtility.Machine.Output.Counts |
默认机器行为的直接产品。 | 并行列表:物品 ID 和整数数量。 |
HyDustryUtility.Machine.Requiere.Items / HyDustryUtility.Machine.Requiere.Counts |
所需原料。代码字面使用 Requiere,拼写完全如此。 |
并行列表:ID 和整数数量。 |
HyDustryUtility.Machine.Fuel.Items / HyDustryUtility.Machine.Fuel.Counts |
可用燃料及各自数量。 | 并行列表:ID 和整数数量。 |
HyDustryUtility.Machine.Fuel.Upgrades.N.* |
升级等级 N 的原料和生产时间。 | 参见“燃料与升级”部分。 |
HyDustryUtility.Machine.Scanner.Require.Items |
其存在会触发 Extractor 中原料的验证和消耗。 |
一个标志;内容不被读取。 |
HyDustryUtility.Machine.Scanner.Positions |
提取器要扫描的方块的相对偏移。 | 坐标字符串列表。 |
HyDustryUtility.Machine.Scanner.Blocks |
提取器识别的掉落物 ID 的有序列表。索引决定输出组。 | ID 字符串列表。 |
HyDustryUtility.Machine.Output.Items.N / HyDustryUtility.Machine.Output.Counts.N |
与 Scanner.Blocks 索引 N 关联的输出配方。 |
并行列表:物品 ID 和整数数量。 |
HyDustryUtility.Machine.Output.Items / HyDustryUtility.Machine.Output.Multiplicator |
在提取器中,这将检测到的 ID 与其倍率关联。 | 并行列表:资源 ID 和小数倍率。 |
HyDustryUtility.Machine.Output.Multiplicator.Timer.ID |
按指定 ID 检测到的数量索引的时间值。 | 毫秒值数组(作为字符串);参见关于索引的说明。 |
HyDustryUtility.Machine.Output.Timer.N |
由辅助辅助程序为索引 N 读取的键。 | 整数(作为字符串);当前未被 Extractor.Execute 使用。 |
HyDustryUtility.Machine.Fuel.Scanner.Upgrades.N.Items / ...Multiplicator |
通过燃料升级解锁的扫描器倍率。 | ID 和小数值的并行列表。 |
HyDustryUtility.Paths |
传送带上物体跟随的本地路径点。 | 坐标字符串的有序列表。 |
HyDustryUtility.Behaviour |
一个标志,允许监听器将方块视为传送带表面;值本身不被读取。 | 基于存在的标志。 |
HyDustryUtility.Behaviour.Loocking |
当物体接触传送带时激活持续搜索状态。注意:代码中该键拼写为 Loocking |
正在加载版本记录…
正在加载评论…
评论在新手盒子客户端中发表,这里同步展示。