Skip to content

Commit c05f264

Browse files
Circulate233Circulate233
committed
一些规范性处理
1 parent 2447be4 commit c05f264

3 files changed

Lines changed: 238 additions & 70 deletions

File tree

‎src/main/java/com/circulation/circulation_networks/api/API.java‎

Lines changed: 236 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,12 @@
33
import com.circulation.circulation_networks.api.node.IEnergySupplyNode;
44
import com.circulation.circulation_networks.api.node.INode;
55
import com.circulation.circulation_networks.manager.EnergyMachineManager;
6+
import com.circulation.circulation_networks.manager.HubChannelManager;
67
import com.circulation.circulation_networks.manager.NetworkManager;
78
import com.circulation.circulation_networks.registry.RegistryEnergyHandler;
89
import com.circulation.circulation_networks.registry.RegistryNodes;
910
import it.unimi.dsi.fastutil.objects.ReferenceSet;
11+
import net.minecraft.item.ItemStack;
1012
import net.minecraft.tileentity.TileEntity;
1113
import net.minecraft.util.math.BlockPos;
1214
import net.minecraft.util.math.ChunkPos;
@@ -16,66 +18,164 @@
1618
import javax.annotation.Nullable;
1719
import java.util.Collection;
1820
import java.util.Set;
21+
import java.util.UUID;
1922

2023
/**
21-
* 仅作为一个API方法汇总
22-
* 这个类的方法不应该被重命名
24+
* 仅作为一个API方法汇总。
25+
* 这个类的方法不应该被重命名。
26+
* <p>
27+
* A collection of public-facing API methods.
28+
* Methods of this class should not be renamed.
2329
*/
2430
@SuppressWarnings("unused")
2531
public final class API {
2632

33+
// -------------------------------------------------------------------------
34+
// 节点查询 / Node queries
35+
// -------------------------------------------------------------------------
36+
2737
/**
28-
* @param world 节点所在的世界
29-
* @param pos 节点位置
30-
* @return 可能存在的节点
31-
* 可以捕获到未被加载的区块的节点
38+
* 根据坐标获取节点。可以获取到未被加载区块内的节点。
39+
* <p>
40+
* Returns the node at the given position. Works even for nodes in unloaded chunks.
41+
*
42+
* @param world 节点所在的世界 / the world the node resides in
43+
* @param pos 节点位置 / the position to look up
44+
* @return 该位置的节点，若不存在则为 {@code null} / the node at that position, or {@code null} if absent
3245
*/
3346
@Nullable
3447
public static INode getNodeAt(@Nonnull World world, @Nonnull BlockPos pos) {
3548
return NetworkManager.INSTANCE.getNodeFromPos(world, pos);
3649
}
3750

3851
/**
39-
* @return 全部可用状态的网络
52+
* 返回当前所有处于活跃状态的节点。
53+
* <p>
54+
* Returns all currently active nodes.
55+
*
56+
* @return 全部活跃节点 / all active nodes
57+
*/
58+
@Nonnull
59+
public static ReferenceSet<INode> getAllNodes() {
60+
return NetworkManager.INSTANCE.getActiveNodes();
61+
}
62+
63+
/**
64+
* 返回当前所有处于可用状态的网格。
65+
* <p>
66+
* Returns all currently active grids.
67+
*
68+
* @return 全部活跃网格 / all active grids
4069
*/
4170
@Nonnull
4271
public static Collection<IGrid> getAllGrids() {
4372
return NetworkManager.INSTANCE.getAllGrids();
4473
}
4574

4675
/**
47-
* @param world 节点所在的世界
48-
* @param pos 被检查的位置
49-
* @return 可能可以链接这个位置上节点的所有节点
76+
* 获取链接范围覆盖指定位置所在区块的所有节点。
77+
* <p>
78+
* Returns all nodes whose link scope covers the chunk that contains the given position.
79+
*
80+
* @param world 节点所在的世界 / the world to search in
81+
* @param pos 被检查的位置 / the position to check
82+
* @return 可能可以链接该位置上节点的所有节点 / all nodes that may link to nodes at that position
5083
*/
5184
@Nonnull
5285
public static ReferenceSet<INode> getNodesCoveringPos(@Nonnull World world, @Nonnull BlockPos pos) {
5386
return NetworkManager.INSTANCE.getNodesCoveringPosition(world, pos);
5487
}
5588

5689
/**
57-
* @param pos 目标位置
58-
* @return 可能为此位置的机器供能的所有节点
90+
* 获取链接范围覆盖指定区块的所有节点。
91+
* <p>
92+
* Returns all nodes whose link scope covers the given chunk.
93+
*
94+
* @param world 节点所在的世界 / the world to search in
95+
* @param chunkX 被检查的区块 X 坐标 / the chunk X coordinate
96+
* @param chunkZ 被检查的区块 Z 坐标 / the chunk Z coordinate
97+
* @return 可能可以链接该区块中节点的所有节点 / all nodes that may link to nodes in that chunk
98+
*/
99+
@Nonnull
100+
public static ReferenceSet<INode> getNodesCoveringChunk(@Nonnull World world, int chunkX, int chunkZ) {
101+
return NetworkManager.INSTANCE.getNodesCoveringPosition(world, chunkX, chunkZ);
102+
}
103+
104+
/**
105+
* 获取链接范围覆盖指定区块的所有节点。
106+
* <p>
107+
* Returns all nodes whose link scope covers the given chunk.
108+
*
109+
* @param world 节点所在的世界 / the world to search in
110+
* @param pos 被检查的区块 / the chunk to check
111+
* @return 可能可以链接该区块中节点的所有节点 / all nodes that may link to nodes in that chunk
112+
* @deprecated 使用 {@link #getNodesCoveringChunk(World, int, int)} 代替
113+
* / use {@link #getNodesCoveringChunk(World, int, int)} instead
114+
*/
115+
@Nonnull
116+
@Deprecated
117+
public static ReferenceSet<INode> getNodesCoveringChunk(@Nonnull World world, @Nonnull ChunkPos pos) {
118+
return NetworkManager.INSTANCE.getNodesCoveringPosition(world, pos.x, pos.z);
119+
}
120+
121+
/**
122+
* 返回位于指定区块内的所有节点。
123+
* <p>
124+
* Returns all active nodes located inside the given chunk.
125+
*
126+
* @param world 节点所在的世界 / the world to search in
127+
* @param chunkX 节点所在区块的 X 坐标 / the chunk X coordinate
128+
* @param chunkZ 节点所在区块的 Z 坐标 / the chunk Z coordinate
129+
* @return 区块中所有的生效节点 / all active nodes inside that chunk
130+
*/
131+
@Nonnull
132+
public static ReferenceSet<INode> getNodesInChunk(@Nonnull World world, int chunkX, int chunkZ) {
133+
return NetworkManager.INSTANCE.getNodesInChunk(world, chunkX, chunkZ);
134+
}
135+
136+
// -------------------------------------------------------------------------
137+
// 能量节点 / Energy supply nodes
138+
// -------------------------------------------------------------------------
139+
140+
/**
141+
* 返回供能范围覆盖指定位置所在区块的所有能量供应节点。
142+
* <p>
143+
* Returns all energy supply nodes whose energy scope covers the chunk containing the given position.
144+
*
145+
* @param world 目标世界 / the world to search in
146+
* @param pos 目标位置 / the position to query
147+
* @return 可能为此位置的机器供能的所有节点 / all nodes that may supply energy to machines at that position
59148
*/
60149
@Nonnull
61150
public static ReferenceSet<IEnergySupplyNode> getEnergyNodes(@Nonnull World world, @Nonnull BlockPos pos) {
62151
return EnergyMachineManager.INSTANCE.getEnergyNodes(world, pos);
63152
}
64153

65154
/**
66-
* @param chunkX 目标区块的X坐标
67-
* @param chunkZ 目标区块的Z坐标
68-
* @return 可能为此区块的机器供能的所有节点
155+
* 返回供能范围覆盖指定区块的所有能量供应节点。
156+
* <p>
157+
* Returns all energy supply nodes whose energy scope covers the given chunk.
158+
*
159+
* @param world 目标世界 / the world to search in
160+
* @param chunkX 目标区块的 X 坐标 / the chunk X coordinate
161+
* @param chunkZ 目标区块的 Z 坐标 / the chunk Z coordinate
162+
* @return 可能为此区块供能的所有节点 / all nodes that may supply energy to machines in that chunk
69163
*/
70164
@Nonnull
71165
public static ReferenceSet<IEnergySupplyNode> getEnergyNodes(@Nonnull World world, int chunkX, int chunkZ) {
72166
return EnergyMachineManager.INSTANCE.getEnergyNodes(world, chunkX, chunkZ);
73167
}
74168

75169
/**
76-
* @param pos 目标位置
77-
* @return 可能为此位置的机器供能的所有节点
170+
* 返回供能范围覆盖指定区块的所有能量供应节点。
171+
* <p>
172+
* Returns all energy supply nodes whose energy scope covers the given chunk.
173+
*
174+
* @param world 目标世界 / the world to search in
175+
* @param pos 目标区块 / the chunk to query
176+
* @return 可能为此区块的机器供能的所有节点 / all nodes that may supply energy to machines in that chunk
78177
* @deprecated 使用 {@link #getEnergyNodes(World, int, int)} 或 {@link #getEnergyNodes(World, BlockPos)} 代替
178+
* / use {@link #getEnergyNodes(World, int, int)} or {@link #getEnergyNodes(World, BlockPos)} instead
79179
*/
80180
@Nonnull
81181
@Deprecated
@@ -84,76 +184,151 @@ public static ReferenceSet<IEnergySupplyNode> getEnergyNodes(@Nonnull World worl
84184
}
85185

86186
/**
87-
* @param world 节点所在的世界
88-
* @param chunkX 被检查的区块X坐标
89-
* @param chunkZ 被检查的区块Z坐标
90-
* @return 可能可以链接这个区块中节点的所有节点
187+
* 返回指定能量供应节点当前所链接的所有设备。
188+
* 注意：返回的设备可能包含带有 {@code IMachineNode} 的实体。
189+
* <p>
190+
* Returns all machines currently supplied by the given energy supply node.
191+
* Note: the returned set may include tile entities that also carry an {@code IMachineNode}.
192+
*
193+
* @param node 节点，不应该是 {@code IMachineNode} / the supply node (should not be an IMachineNode)
194+
* @return 节点所供能的所有设备 / all machines supplied by this node
91195
*/
92196
@Nonnull
93-
public static ReferenceSet<INode> getNodesCoveringChunk(@Nonnull World world, int chunkX, int chunkZ) {
94-
return NetworkManager.INSTANCE.getNodesCoveringPosition(world, chunkX, chunkZ);
197+
public static Set<TileEntity> getMachinesSuppliedBy(@Nonnull IEnergySupplyNode node) {
198+
return EnergyMachineManager.INSTANCE.getMachinesSuppliedBy(node);
95199
}
96200

201+
// -------------------------------------------------------------------------
202+
// 中枢频道 / Hub channels
203+
// -------------------------------------------------------------------------
204+
97205
/**
98-
* @param world 节点所在的世界
99-
* @param pos 被检查的区块
100-
* @return 可能可以链接这个区块中节点的所有节点
101-
* @deprecated 使用 {@link #getNodesCoveringChunk(World, int, int)} 代替
206+
* 返回指定频道 UUID 所关联的所有网格。
207+
* 中枢节点（{@code IHubNode}）通过相同的频道 UUID 跨网格共享能量。
208+
* <p>
209+
* Returns all grids associated with the given hub channel UUID.
210+
* Hub nodes ({@code IHubNode}) share energy across grids that share the same channel UUID.
211+
*
212+
* @param channelId 频道 UUID / the channel UUID
213+
* @return 属于该频道的所有网格，若频道不存在则为 {@code null}
214+
* / all grids in this channel, or {@code null} if the channel does not exist
102215
*/
103-
@Nonnull
104-
@Deprecated
105-
public static ReferenceSet<INode> getNodesCoveringChunk(@Nonnull World world, @Nonnull ChunkPos pos) {
106-
return NetworkManager.INSTANCE.getNodesCoveringPosition(world, pos.x, pos.z);
216+
@Nullable
217+
public static ReferenceSet<IGrid> getChannelGrids(@Nonnull UUID channelId) {
218+
return HubChannelManager.INSTANCE.getChannelGrids(channelId);
107219
}
108220

221+
// -------------------------------------------------------------------------
222+
// 能量类型判断 / Energy type checks
223+
// -------------------------------------------------------------------------
224+
109225
/**
110-
* @param world 节点所在的世界
111-
* @param chunkX 节点所在的区块X坐标
112-
* @param chunkZ 节点所在的区块Z坐标
113-
* @return 区块中所有的生效节点
226+
* 判断指定 TileEntity 是否位于能源全局黑名单中。
227+
* 黑名单中的实体不会被任何节点识别为能源容器。
228+
* <p>
229+
* Returns whether the given TileEntity is on the global energy blacklist.
230+
* Blacklisted entities are never recognized as energy containers by any node.
231+
*
232+
* @param tileEntity 目标实体 / the tile entity to check
233+
* @return 是否在黑名单中 / {@code true} if blacklisted
114234
*/
115-
@Nonnull
116-
public static ReferenceSet<INode> getNodesInChunk(@Nonnull World world, int chunkX, int chunkZ) {
117-
return NetworkManager.INSTANCE.getNodesInChunk(world, chunkX, chunkZ);
235+
public static boolean isEnergyBlacklisted(@Nonnull TileEntity tileEntity) {
236+
return RegistryEnergyHandler.isBlack(tileEntity);
118237
}
119238

120239
/**
121-
* @param world 节点所在的世界
122-
* @param chunk 节点所在的区块
123-
* @return 区块中所有的生效节点
124-
* @deprecated 使用 {@link #getNodesInChunk(World, int, int)} 代替
240+
* 判断指定 TileEntity 是否位于通用供应节点黑名单中。
241+
* 黑名单中的实体只能由覆写了 {@code isBlacklisted} 的专用节点建立连接，普通供应节点无法连接。
242+
* <p>
243+
* Returns whether the given TileEntity is on the supply-node blacklist.
244+
* Blacklisted entities can only be connected by specialized nodes that override {@code isBlacklisted};
245+
* generic supply nodes cannot connect to them.
246+
*
247+
* @param tileEntity 目标实体 / the tile entity to check
248+
* @return 是否在供应黑名单中 / {@code true} if on the supply blacklist
125249
*/
126-
@Nonnull
127-
@Deprecated
128-
public static ReferenceSet<INode> getNodesInChunk(@Nonnull World world, @Nonnull ChunkPos chunk) {
129-
return NetworkManager.INSTANCE.getNodesInChunk(world, chunk.x, chunk.z);
250+
public static boolean isSupplyBlacklisted(@Nonnull TileEntity tileEntity) {
251+
return RegistryEnergyHandler.isSupplyBlack(tileEntity);
130252
}
131253

132254
/**
133-
* 注册自定义的能量管理器
134-
* 只允许在postinit阶段前进行注册
255+
* 判断指定物品堆是否为受能量处理器管理的能源物品。
256+
* <p>
257+
* Returns whether the given item stack is an energy item handled by a registered energy manager.
258+
*
259+
* @param stack 目标物品堆 / the item stack to check
260+
* @return 是否为能源物品 / {@code true} if the item is an energy item
135261
*/
136-
public static void registerEnergyHandler(@Nonnull IEnergyHandlerManager manager) {
137-
RegistryEnergyHandler.registerEnergyHandler(manager);
262+
public static boolean isEnergyItem(@Nonnull ItemStack stack) {
263+
return RegistryEnergyHandler.isEnergyItemStack(stack);
138264
}
139265

140266
/**
141-
* @param nodeClass 节点的class
142-
* @param function 从NBT中反序列化回节点的方法
267+
* 判断指定 TileEntity 是否为受能量处理器管理的能源容器。
268+
* <p>
269+
* Returns whether the given TileEntity is an energy container handled by a registered energy manager.
270+
*
271+
* @param tileEntity 目标实体 / the tile entity to check
272+
* @return 是否为能源容器 / {@code true} if the tile entity is an energy container
143273
*/
144-
public static void registerNode(@Nonnull Class<? extends INode> nodeClass, @Nonnull RegistryNodes.DeserializationNode function) {
145-
RegistryNodes.register(nodeClass, function);
274+
public static boolean isEnergyTileEntity(@Nonnull TileEntity tileEntity) {
275+
return RegistryEnergyHandler.isEnergyTileEntity(tileEntity);
146276
}
147277

148278
/**
149-
* @param node 节点，不应该是机器节点
150-
* @return 节点所供能的所有设备
151-
* 注意：返回的设备可能包含带有IMachineNode的设备
279+
* 获取适用于指定 TileEntity 的能量处理器管理器。
280+
* <p>
281+
* Returns the energy handler manager compatible with the given TileEntity,
282+
* or {@code null} if no registered manager applies.
283+
*
284+
* @param tileEntity 目标实体 / the tile entity to query
285+
* @return 匹配的能量管理器，若无匹配则为 {@code null} / a matching manager, or {@code null} if none applies
152286
*/
153-
@Nonnull
154-
public Set<TileEntity> getMachinesSuppliedBy(IEnergySupplyNode node) {
155-
return EnergyMachineManager.INSTANCE.getMachinesSuppliedBy(node);
287+
@Nullable
288+
public static IEnergyHandlerManager getEnergyManager(@Nonnull TileEntity tileEntity) {
289+
return RegistryEnergyHandler.getEnergyManager(tileEntity);
156290
}
157291

292+
/**
293+
* 获取适用于指定物品堆的能量处理器管理器。
294+
* <p>
295+
* Returns the energy handler manager compatible with the given item stack,
296+
* or {@code null} if no registered manager applies.
297+
*
298+
* @param stack 目标物品堆 / the item stack to query
299+
* @return 匹配的能量管理器，若无匹配则为 {@code null} / a matching manager, or {@code null} if none applies
300+
*/
301+
@Nullable
302+
public static IEnergyHandlerManager getEnergyManager(@Nonnull ItemStack stack) {
303+
return RegistryEnergyHandler.getEnergyManager(stack);
304+
}
158305

159-
}
306+
// -------------------------------------------------------------------------
307+
// 注册 / Registration
308+
// -------------------------------------------------------------------------
309+
310+
/**
311+
* 注册自定义的能量管理器。
312+
* 只允许在 postInit 阶段前进行注册。
313+
* <p>
314+
* Registers a custom energy handler manager.
315+
* Must be called before the postInit phase.
316+
*
317+
* @param manager 要注册的能量管理器 / the manager to register
318+
*/
319+
public static void registerEnergyHandler(@Nonnull IEnergyHandlerManager manager) {
320+
RegistryEnergyHandler.registerEnergyHandler(manager);
321+
}
322+
323+
/**
324+
* 注册自定义节点类型及其 NBT 反序列化函数。
325+
* <p>
326+
* Registers a custom node class together with its NBT deserialization function.
327+
*
328+
* @param nodeClass 节点的 class / the node class to register
329+
* @param function 从 NBT 中反序列化回节点的方法 / function to deserialize a node from NBT
330+
*/
331+
public static void registerNode(@Nonnull Class<? extends INode> nodeClass, @Nonnull RegistryNodes.DeserializationNode function) {
332+
RegistryNodes.register(nodeClass, function);
333+
}
334+
}

0 commit comments

Comments
 (0)