HyDustry 库

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